Skip to main content
The API has three kinds of credential, and each surface accepts only the one meant for it. OAuth access tokens are issued for the audience https://api.ai2fin.com/mcp. They work on /mcp and the Integration API and are refused on the rest of /api/.... Session tokens are the reverse. API keys work on the MCP Inspector endpoint only (a partner sandbox account’s own key also works on the Integration API).

Session tokens (REST API)

Sign in with POST /api/enterprise-auth/login. A successful response carries token (send it as a bearer token), your user and sessionInfo.expiresIn in seconds, and also sets the session cookie. If the account has two-factor sign-in turned on, the first response is mfaRequired: true and the sign-in finishes at POST /api/enterprise-auth/mfa/verify. The REST API returns your own account’s data to you. It is a first-party surface for your own scripts and the 2Fin apps, not a channel for third parties: a third-party tool should use OAuth, which asks you to approve it.

OAuth 2.1 (assistants and integrations)

A person always signs in and approves the grant on 2Fin’s consent screen, which names every scope requested and offers a read-only choice when writes are asked for. The full MCP walk-through is in MCP authentication.

Scopes

An authorization request with no scope gets the client’s registered scopes, or, for a client registered without any, read:transactions write:transactions read:bills write:bills. write:expenses and webhooks:manage are never given by default: ask for them by name. A scope outside this list is refused with invalid_scope.

A missing scope

On the Integration API a token without the needed scope gets 403:
On /mcp the write tool answers with a JSON-RPC insufficient_scope error instead, as described in MCP authentication. GET /api/integrations/v1/me accepts any valid token and returns the scopes it carries, which is a quick way to check a connection.

API keys (MCP Inspector)

Create a key in the dashboard or with POST /api/api-keys using your session token. The key is shown once.
  • Keys look like mcp_ followed by 64 hex characters and are stored only as a SHA-256 hash.
  • A key expires after 90 days unless you choose a different lifetime, up to 365 days.
  • Key scopes are separate from OAuth scopes: mcp:read, mcp:tools:list, mcp:tools:call:readonly, mcp:tools:call, mcp:resources:read, mcp:prompts:read and mcp:full.
  • List your keys with GET /api/api-keys and revoke one the moment it is no longer needed.

Errors