# Authentication

Thumbn exposes an MCP server and a REST API. Both act as a signed-in
Thumbn account: the same plan, the same credit balance, the same limits as
the web app. There is no anonymous access tier.

## MCP (recommended for AI agents)

- Endpoint: `https://api.thumbn.so/mcp`
- Transport: Streamable HTTP
- Authorization: OAuth 2.1, authorization code with PKCE

Discovery:

- Protected resource metadata (RFC 9728): `https://api.thumbn.so/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://api.thumbn.so/.well-known/oauth-authorization-server`
- Server card (SEP-1649): `https://thumbn.so/.well-known/mcp/server-card.json`

Dynamic client registration is supported, so a client may register itself:

- `register_uri`: `https://api.thumbn.so/auth/mcp/register`
- `authorization_endpoint`: `https://api.thumbn.so/auth/mcp/authorize`
- `token_endpoint`: `https://api.thumbn.so/auth/mcp/token`

An unauthenticated request to the MCP endpoint answers `401` with a
`WWW-Authenticate` header carrying `resource_metadata`, which is the intended
entry point to the flow.

The user completes the consent step in a browser. Agents that cannot open one
should use an API key instead.

## API keys

- Header: `x-api-key: sk_...` (also accepted as `Authorization: Bearer sk_...`)
- Issued at: https://thumbn.so/settings
- Shown once at creation; stored only as a hash and unrecoverable afterwards.
- Revocable at any time from the same page. A revoked key answers `401`.

Keys are per-user, not per-organisation, and inherit that user's plan.

## Identity and cost

- Identity type: existing human account (Google sign-in).
- Credential types: OAuth 2.1 access token, or API key.
- Registration for agents: dynamic client registration for OAuth clients only —
  it registers a *client*, not a user. A human account is still required.
- Cost: creating thumbnails requires an active subscription and spends credits.
  Reading existing work does not. Call the `estimate_cost` tool, or
  `GET https://api.thumbn.so/billing/summary`, for exact figures before spending.

## Rate limits

Requests are throttled per IP and per account. Exceeding a limit answers `429`
with `{"code": "rate_limited"}`. Back off and retry.

## Documentation

https://thumbn.so/developers (Markdown: https://thumbn.so/md/developers)
