# 2Fin auth.md

How an agent signs in to 2Fin on behalf of a person, and which 2Fin surfaces need no sign-in at all.

## Who this is for

AI agents and assistants acting for a 2Fin user: reading their transactions, bills, budgets and tax position, and making changes they approve. Every token is bound to one person, one client and the scopes that person granted.

## The protected resource

- Resource: `https://api.ai2fin.com/mcp` (Model Context Protocol, Streamable HTTP)
- Protected-resource metadata: `https://api.ai2fin.com/.well-known/oauth-protected-resource/mcp`
- A request without a token gets `401` with a `WWW-Authenticate` header pointing at that metadata.
- Root metadata (RFC 9728): `https://api.ai2fin.com/.well-known/oauth-protected-resource` names the origin `https://api.ai2fin.com`. The authorization server accepts that origin as an alias for `https://api.ai2fin.com/mcp`, and the token it issues is still for `/mcp` only.

## Authorization server

- Issuer: `https://api.ai2fin.com/api/oauth`
- Metadata (RFC 8414): `https://api.ai2fin.com/.well-known/oauth-authorization-server`
- Read the endpoints from the metadata rather than hard-coding them. Today they are:
  - authorization: `https://api.ai2fin.com/api/oauth/authorize`
  - token: `https://api.ai2fin.com/api/oauth/token`
  - registration: `https://api.ai2fin.com/api/oauth/register`
  - revocation: `https://api.ai2fin.com/api/oauth/revoke`

## Register your client

Registration is open. Either:

1. **Dynamic Client Registration (RFC 7591):** `POST` your client metadata to the `registration_endpoint` above. Redirect URIs must be HTTPS, or a loopback address for an app on the person's own device, and are matched exactly.
2. **Client ID Metadata Document:** use an HTTPS URL that serves your client metadata as your `client_id` (`client_id_metadata_document_supported: true`).

A client that registers without naming scopes may ask for up to `read:transactions write:transactions read:bills write:bills`. A client that names scopes at registration can never be granted more than those.

## Get a token: OAuth 2.1 authorization code + PKCE

1. Create a `code_verifier` and its `code_challenge` with **S256**. PKCE is required; `plain` is refused.
2. Send the person to the authorization endpoint with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `code_challenge_method=S256` and `resource=https://api.ai2fin.com/mcp` (RFC 8707; the origin `https://api.ai2fin.com` is accepted as an alias for it, and any other resource is refused with `invalid_target`).
3. The person signs in to 2Fin and sees the consent screen: your client's name, the redirect address and every scope by name. They choose **Allow**, **Allow read-only access** or **Deny**. No client can skip this screen.
4. Exchange the code at the token endpoint with the `code_verifier` and the same `resource=https://api.ai2fin.com/mcp`. You receive an access token and a refresh token.
5. Refresh with `grant_type=refresh_token` before the short-lived access token expires. Revoke at the revocation endpoint when you are done.

## Scopes

| Scope | What it allows |
| - | - |
| `read:transactions` | Read transactions, spending, categories, budgets, income, insights, assets, places and tax summaries |
| `read:bills` | Read bills and bill occurrences |
| `write:transactions` | Create and change records: transactions, receipts, expenses, trips, budgets, goals, assets, tax statements |
| `write:bills` | The same write tools (either write scope unlocks them) |

**Read** needs only the read scopes. **Write** needs a write scope, and the person must approve it on the consent screen; if they choose read-only, every write call returns `insufficient_scope` and nothing changes. For most clients, 2Fin also asks for a confirmation step before each change: the first write call returns `needsConfirmation: true` with a short-lived `confirmToken` and a preview to show the person; repeat the call with that token once they agree.

## Call the API with a bearer token

Send the access token in the `Authorization` header on every request:

```http
POST /mcp HTTP/1.1
Host: api.ai2fin.com
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"your-agent","version":"1.0"}}}
```

The header is the only bearer method the resource supports (`bearer_methods_supported: ["header"]`).`401` means the token is missing, expired or invalid: refresh it or start the flow again.

## No auth needed: the 2Fin Tax MCP

`https://taxmcp.ai2fin.com` is public and stateless: tax rates and calculators with no login, no API key and nothing stored. Connect to it directly; there is nothing to register. It never sees anyone's 2Fin data. Server card: `https://taxmcp.ai2fin.com/.well-known/mcp/server-card.json`.

## More

- MCP docs: https://docs.ai2fin.com/mcp/introduction
- MCP server card: https://api.ai2fin.com/.well-known/mcp/server-card.json
- API catalog: https://api.ai2fin.com/.well-known/api-catalog
- Agent skills: https://api.ai2fin.com/.well-known/agent-skills/index.json
- For agents: https://api.ai2fin.com/llms.txt
