# Authentication (/authentication)



## API keys [#api-keys]

Send an API key as a bearer token on every API request:

```http
POST /v1/score HTTP/1.1
Host: api.finic.ai
Authorization: Bearer gsk_…
```

Create keys in the Finic Portal under [API keys](https://portal.finic.ai/keys). A key starts with `gsk_` and is shown once, when you create it; if you lose it, create a new one. Each key expires after the time you choose: 1 hour, 1 day, 7 days, 30 days (the default), 90 days, 1 year or never.

Keys belong to your organization, and Usage in the Finic Portal is broken down by key, so use one key per service and environment.

* **Keep keys server-side,** in environment variables or a secrets manager. Never put one in browser or mobile code, or in source control. Don't log the `Authorization` header.
* **Rotate without downtime:** create a new key, deploy it, check under Usage that the old one has stopped receiving requests, then revoke it under [API keys](https://portal.finic.ai/keys).

A missing, unknown, revoked or expired key gets `401 authentication_error`.

## MCP sign-in [#mcp-sign-in]

[`https://api.finic.ai/mcp`](/agent-quickstart) uses OAuth, so agents never handle a key:

1. The first time an agent connects, your app shows you a sign-in link to the Finic Portal.
2. You sign in, or create an account there (email and password, or Google), and approve access for one of your organizations. Only approve if you're connecting that app right now.
3. You're sent back to the app, which receives its token automatically and renews it. After 90 days without use, you sign in again.

Each signed-in app is listed under [API keys](https://portal.finic.ai/keys) as its name followed by "(sign-in)". Its calls count toward that organization's usage, credit and rate limits. Choose **Sign out** there to disconnect it.

`/mcp` also accepts an API key as `Authorization: Bearer gsk_…`, for scripts and CI. For clients that can't sign in or send headers, [`/mcp/keys`](/mcp/sign-up) has a link-and-key flow: you approve an API key, and the agent receives it.

### For MCP client developers [#for-mcp-client-developers]

`/mcp` follows MCP's authorization spec (OAuth 2.1):

* **Discovery:** an unauthenticated request gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.finic.ai/.well-known/oauth-protected-resource/mcp", scope="decide"`.
* **Authorization server:** `https://portal.finic.ai`, metadata at `/.well-known/oauth-authorization-server`.
* **Registration:** client ID metadata documents, or dynamic client registration (RFC 7591).
* **Requests:** authorization code with PKCE (`S256` only), resource `https://api.finic.ai/mcp`, scope `decide`.
* **Tokens:** access tokens last 1 hour; refresh tokens last 90 days and are replaced on each use.

## The docs' playground [#the-docs-playground]

The API reference pages' playground sends real requests. If you're signed in to the [Finic Portal](https://portal.finic.ai) in the same browser, they use your session: requests run against your current organization and are billed like any API request. Otherwise, paste an API key; it's kept in that browser tab only.
