> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai2fin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scopes — session tokens, OAuth and API keys

> Which credential each part of the 2Fin API accepts, the OAuth 2.1 endpoints and the six scopes, how session tokens and API keys work, and what a missing scope returns.

The API has three kinds of credential, and each surface accepts only the one meant for it.

| Surface | Credential | Header |
| - | - | - |
| REST API, `/api/...` | Your own signed-in session: a session token, or the `ai2_sess` cookie in the browser | `Authorization: Bearer <token>` |
| MCP, `/mcp` | An OAuth access token you approved for an assistant | `Authorization: Bearer <token>` |
| Integration API, `/api/integrations/v1` | An OAuth access token carrying the scope the endpoint needs | `Authorization: Bearer <token>` |
| MCP Inspector, `/mcp/inspector` | An API key | `X-API-Key: mcp_…` |

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)

| | |
| - | - |
| Discovery | `https://api.ai2fin.com/.well-known/oauth-authorization-server` and `https://api.ai2fin.com/.well-known/oauth-protected-resource/mcp` |
| Authorize | `https://api.ai2fin.com/api/oauth/authorize` |
| Token | `https://api.ai2fin.com/api/oauth/token` |
| Register (RFC 7591) | `https://api.ai2fin.com/api/oauth/register`, open, no initial access token. Client ID Metadata Documents are also accepted. |
| Pushed authorization requests (RFC 9126) | `https://api.ai2fin.com/api/oauth/par` |
| Revoke (RFC 7009) | `https://api.ai2fin.com/api/oauth/revoke` |
| Grants | `authorization_code` and `refresh_token` only. No implicit or password grant. |
| PKCE | Required, `S256` only. Redirect URIs must match exactly. |
| Client authentication | `client_secret_basic`, `client_secret_post` or `none` (public clients). |
| Tokens | Access tokens last one hour. Refresh tokens rotate on use. DPoP-bound tokens are supported but not required. |

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](https://docs.ai2fin.com/mcp/authentication.md).

### Scopes

| Scope | Grants |
| - | - |
| `read:transactions` | MCP read tools over transactions, spending, tax summaries, categories, lenses, budgets, income, insights, assets, places, expected income, upcoming money, account and plan |
| `read:bills` | MCP read tools over bills and bill occurrences |
| `write:transactions` | MCP write tools. Integration API `POST /transactions` and `POST /statements` |
| `write:bills` | MCP write tools (the same gate as `write:transactions`; either one unlocks them) |
| `write:expenses` | Integration API `POST /expenses`. Does not unlock MCP write tools |
| `webhooks:manage` | Integration API `GET`, `POST /webhooks` and `DELETE /webhooks/{id}`. The account also needs the Auto+ plan. Does not unlock MCP write tools |

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`:

```http theme={null}
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="https://api.ai2fin.com/api/integrations/v1", error="insufficient_scope", scope="write:expenses"

{ "success": false, "error": "Missing required scope: write:expenses", "errorType": "INSUFFICIENT_SCOPE", "grantedScopes": ["read:transactions"] }
```

On `/mcp` the write tool answers with a JSON-RPC `insufficient_scope` error instead, as described in [MCP authentication](https://docs.ai2fin.com/mcp/authentication.md#errors).

`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

| Status | Meaning |
| - | - |
| `401` | No credential, or it is expired, revoked or for the wrong surface. OAuth surfaces add a `WWW-Authenticate` header. |
| `403` | Signed in, but the plan, the team role or the token's scopes do not cover this. The body says which (`requiredPlan`, `errorType: "INSUFFICIENT_SCOPE"`). |
| `429` | Rate limited. See [Rate limits](https://docs.ai2fin.com/api-reference/rate-limits.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.