Authentication

The Cashfin MCP server supports two ways to authenticate:

Method	Use it for	Credential
OAuth (recommended)	Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code, Windsurf and any client with OAuth support	Short-lived access token + rotating refresh token, issued after you sign in and approve
URL token	Clients that cannot do OAuth	A long-lived token embedded in the server URL

Both are tied to one business and to the person who created them.

• OAuth
  • Endpoints
  • What is supported
  • The sign-in flow
  • Token lifetimes
• URL tokens
• Access always follows your Cashfin access
• Revoking access

OAuth

Endpoints

	URL
MCP endpoint	https://storefront.cashfin.africa/mcp
Protected resource metadata	https://storefront.cashfin.africa/.well-known/oauth-protected-resource/mcp
Authorization server metadata	https://storefront.cashfin.africa/.well-known/oauth-authorization-server
Authorization endpoint	https://storefront.cashfin.africa/oauth/authorize
Token endpoint	https://storefront.cashfin.africa/api/oauth/token
Dynamic client registration	https://storefront.cashfin.africa/api/oauth/register

MCP clients discover these automatically. An unauthenticated request to /mcp returns 401 with a WWW-Authenticate header that points to the protected resource metadata.

What is supported

• Grant types: authorization_code and refresh_token.
• PKCE: required, S256 only.
• Client authentication: none (public clients). PKCE protects the exchange.
• Client registration: Dynamic Client Registration, and Client ID Metadata Documents, where the client_id is an https:// URL.
• Redirect URIs: must match a registered URI exactly. Loopback redirects (http://127.0.0.1/…, http://localhost/…) may use any port, as native clients pick a free port per session.

The sign-in flow

1. The client registers itself (or presents its metadata document URL) and sends you to the authorization endpoint with a PKCE challenge.
2. Cashfin sends you to pick the business on accounts.cashfin.africa, signing you in first if needed.
3. After you pick a business, the consent screen shows the client and the business. Approve issues a single-use authorization code; Deny returns access_denied to the client.
4. The client exchanges the code and its PKCE verifier at the token endpoint for an access token and a refresh token.
5. The client calls /mcp with Authorization: Bearer <access token>.

Token lifetimes

Item	Lifetime
Authorization code	10 minutes, single use
Access token	1 hour
Refresh token	30 days, rotated on every use
Rotated refresh token grace period	30 seconds, so two refreshes racing each other both succeed

When a refresh token is used, the old access token stops working immediately and a new pair is issued. A refresh token only works for the client it was issued to. Refresh tokens are stored hashed.

URL tokens

For clients that cannot do OAuth, create a URL token in the storefront builder:

1. Open the storefront builder for the business (from your Cashfin dashboard).
2. Go to Integrations → MCP.
3. Expand Legacy URL tokens, enter a Connection name, click Generate URL token, and copy the URL. It is shown only once.

The URL looks like this:

https://storefront.cashfin.africa/mcp/ymc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat a URL token like a password

Anyone with the URL can edit and publish that business's storefront. URL tokens do not expire on their own. Never commit one to a repository or paste it into shared chats. Revoke it from Integrations → MCP when you no longer need it.

A URL token works for the business whose builder it was created in, and acts as the person who created it.

Access always follows your Cashfin access

Every token, whether OAuth or URL, is checked against the person who created it. If that person:

• is removed from the business,
• loses builder access in Settings → Users, or
• is suspended or demoted in Cashfin so that they can no longer open the builder,

then their connections stop working within about a minute, and refresh tokens are refused.

Revoking access

In the storefront builder, open Integrations → MCP:

• Connections lists OAuth connections (one per assistant you approved). Revoke one to stop it immediately.
• Legacy URL tokens lists URL tokens. Delete one to stop it immediately.

Removing the connector from your assistant does not revoke the token on Cashfin's side. Revoke it in Cashfin too if the device or account may be compromised.