Authentication

Financy uses OAuth2 client credentials. Before calling any API endpoint you
exchange your credentials for a short-lived access token.

Create a token

POST https://api.open-finance.ai/oauth/token

clientId, clientSecret, and userId are shown in the Financy app under
Settings → API. The data and payment APIs are a paid feature
(Starter or Pro); the same credentials on the Free plan exchange for a
token that then fails every data/payment call with 403 NOT_AVAILABLE_ON_PLAN.

Request

curl -X POST https://api.open-finance.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "userId": "user-1234"
  }'

Response

{
  "accessToken": "eyJhbGciOiJ...",
  "tokenType": "Bearer",
  "expiresIn": 86400
}

Use the token

Send the token on every API request:

curl https://api.open-finance.ai/v2/payments \
  -H "Authorization: Bearer eyJhbGciOiJ..."

Handling expiry & errors

• The token is per user (userId). Request a token for the specific user you
  are acting on behalf of.
• Cache it and reuse it while it is valid; request a fresh token as it nears
  expiry.
• If a request returns 401 Unauthorized, the token has expired or is
  invalid — get a new one from POST /oauth/token and retry. See Errors for
  the full list of status codes and the error response shape.

🔑

Your clientSecret is a server-side secret. Never ship it to a browser,

mobile app, or any client you don't control.

Rotate the secret

Paid users can replace the secret from Settings → API → Rotate key
(Hebrew: סובב מפתח) without changing clientId or userId. Rotation is
irreversible:

• The old clientSecret stops working immediately. Calls authenticated with it
  return 401. Update every integration (financy setup, env vars, secret
  stores) before or immediately after rotating.
• Cached access tokens minted with the old secret are purged when rotation
  succeeds. If the app reports that tokens could not be purged, a token minted
  just before rotation may keep working until it expires (expiresIn) — treat
  that as a leak-response case and contact us.

There is no API to rotate the secret from an integration; it is an in-app
action on the org that owns the key.

MCP connector tokens

API keys are not the only Bearer token this API accepts. A Financy
connector inside an AI client mints a token for the MCP resource
https://mcp.open-finance.ai/ (trailing slash required) with the mcp:read
scope. Those tokens work only on the read routes listed in CLI & AI Agents;
they cannot be obtained from POST /oauth/token, and they cannot be used as a
substitute for clientSecret.