Authentication
API keys from the Finic Portal, sign-in for AI agents over MCP, and how the docs' API playground authenticates.
API keys
Send an API key as a bearer token on every API request:
POST /v1/score HTTP/1.1
Host: api.finic.ai
Authorization: Bearer gsk_…Create keys in the Finic Portal under API 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
Authorizationheader. - 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.
A missing, unknown, revoked or expired key gets 401 authentication_error.
MCP sign-in
https://api.finic.ai/mcp uses OAuth, so agents never handle a key:
- The first time an agent connects, your app shows you a sign-in link to the Finic Portal.
- 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.
- 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 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 has a link-and-key flow: you approve an API key, and the agent receives it.
For MCP client developers
/mcp follows MCP's authorization spec (OAuth 2.1):
- Discovery: an unauthenticated request gets
401withWWW-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 (
S256only), resourcehttps://api.finic.ai/mcp, scopedecide. - Tokens: access tokens last 1 hour; refresh tokens last 90 days and are replaced on each use.
The docs' playground
The API reference pages' playground sends real requests. If you're signed in to the Finic Portal 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.