---
title: "How agents authenticate with Flicker"
canonical: https://flicker.finance/auth.md
---

# How agents authenticate with Flicker

Flicker exposes two programmatic surfaces, each with its own credential. The REST API takes a
self-serve API key; the MCP server takes an OAuth 2.1 bearer token. There is no anonymous tier on
either.

## Discover

- MCP: an unauthenticated request to `https://api.flicker.finance/mcp` answers **401** with the RFC 9728
  challenge `WWW-Authenticate: Bearer resource_metadata="https://api.flicker.finance/.well-known/oauth-protected-resource/mcp"`.
  Follow it to the protected-resource metadata, whose `authorization_servers` names the
  authorization server; its RFC 8414 metadata is at https://api.flicker.finance/.well-known/oauth-authorization-server.
- REST: the machine-readable surface is the OpenAPI 3.1 document at https://api.flicker.finance/docs/openapi.json; the human
  walkthrough is https://flicker.finance/developers.

Flicker publishes no `agent_auth` discovery block: there is no `identity_endpoint`, and neither
`identity_assertion` (the ID-JAG token type `urn:ietf:params:oauth:token-type:id-jag`) nor
`service_auth` assertion exchange is supported. Use one of the two methods below.

## Pick a method

- Reading **market data over REST** (analysis, assets, insights, config, exchanges): use an API key.
- Acting **as a signed-in user over MCP** (portfolio, watchlist, alerts — and all market-data tools
  too, since every MCP tool requires a token): use OAuth 2.1.

## Register

- REST: create a Flicker account at https://flicker.finance/auth — keys are minted from the account, so
  registration is the account itself.
- MCP: the authorization server supports RFC 7591 dynamic client registration; the
  `registration_endpoint` is published in the RFC 8414 metadata above. MCP clients that follow the
  401 challenge register themselves.

## Claim

- REST: mint a key on the **API keys** page at https://flicker.finance/account/api-keys. This is a
  human step — there is no unauthenticated key-minting endpoint.
- MCP: run the authorization-code flow with PKCE (S256) through the endpoints named in the RFC 8414
  metadata. The user approves the connection on Flicker's consent screen.

## Exchange

- REST: nothing to exchange — the key is the credential.
- MCP: exchange the authorization code at the metadata's `token_endpoint`; `refresh_token` grants
  are supported for renewal.

## Use the access_token

- REST: send the key as a request header on every call:
  `curl -H "x-api-key: $FLICKER_API_KEY" https://api.flicker.finance/v2/analysis/bitcoin`.
  A key unlocks the read-only market-data surface only
  (`/v2/analysis`, `/v2/assets`, `/v2/insights`, `/v2/config`, `/v1/exchanges`); it cannot read an account
  or place a trade. Daily credit balance: `GET https://api.flicker.finance/v1/users/api_keys/credits`.
- MCP: send `Authorization: Bearer <access_token>` on the Streamable HTTP transport.

## Errors

- Every REST error body is the `ErrorResponse` shape —
  `{ "success": false, "code": "…", "message": "…" }` — across statuses
  400, 401, 402, 403, 404, 410, 422, 500, 503. Branch on `code`, never on `message`.
- A request with no valid credential gets **403** on REST and **401** with the
  `WWW-Authenticate` challenge on MCP.
- Rate limits: a weighted budget of 2000 units per 60s per
  client IP, reported on every response via `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-used`, `x-ratelimit-window`; a **429** adds
  `retry-after`.

## Revocation

API keys are revoked on the **API keys** page at https://flicker.finance/account/api-keys, OAuth grants
under **Connected AI apps** at https://flicker.finance/account/security#connected-apps. The authorization server
publishes no RFC 7009 revocation endpoint — disconnecting from the account is the revocation path.