Authentication and API keys

How does a REST call authenticate?

Send exactly one credential: Authorization: Bearer followed by an API key or an access token, or x-api-key followed by an API key. Sending both, or an Authorization header with another scheme, is refused with HTTP 401.

What is a Fincanva API key?

• A key starts with fk_, so a leaked one is recognisable.
• One account may hold at most 10 keys at once.
• A key has no expiry date.
• A key works over REST only: the MCP server refuses it.
• Keys are created in «Settings › API», on every paid plan: name the key and press «Create key».
• The full key is shown once, under «You won't see it again»: Fincanva keeps only a fingerprint of it.
• «Rename» changes a key’s name; «Revoke» stops it working at once.

How does OAuth work with Fincanva?

An OAuth 2.1 access token carries the fincanva.research scope and is issued for one surface, REST or MCP, where it works. A client finds where to sign in from the discovery documents:

• the protected-resource metadata, at https://app.fincanva.com/.well-known/oauth-protected-resource;
• the authorization server metadata, at https://app.fincanva.com/.well-known/oauth-authorization-server.

What happens when authentication fails?

A missing, invalid, expired or revoked credential gets HTTP 401 unauthorized, and every such answer carries a WWW-Authenticate header saying what to send. A plan that does not include the surface gets HTTP 403 plan_limit, and details.unlockedBy names the lowest plan that does; Plans, quotas and limits shows which plans include each surface.