Authentication: API keys and OAuth 2.1

FreshlyCited accepts two kinds of credentials. Use an API key for scripts, CI and MCP clients where you can set a header. Use OAuth for connectors like Claude.ai and ChatGPT, where you sign in instead of pasting a secret.

The story · 3 stepsReplay

Your clientFreshlyCitedYou

1. GET /mcp, no token
2. 401 + resource_metadata

The connector calls without a token and is told how to sign in

1. 01 · The problemConnectors need to act as you without ever seeing your password.
2. 02 · What you doOAuth 2.1 with PKCE: sign in, pick a workspace and access level, Allow.
3. 03 · What you getA 1-hour token that refreshes itself; scripts use API keys instead.

Get an API keyFree plan: 10 free links to try (once you verify your email), then 100 free checks a month, no card.

API keys

Create a key under API keys in the app (admins and owners). The secret starts with ipk_ and is shown once. Send it as a bearer token:

curl https://freshlycited.com/api/v1/me -H "Authorization: Bearer ipk_YOUR_KEY"

X-Api-Key: ipk_… works too. A key belongs to one workspace (your agency or a client) and sees only that workspace and the clients under it. Its role decides what it can do: client_viewer keys are read-only. Each key can have its own rate limits and daily credit cap.

OAuth 2.1 for connectors

FreshlyCited implements the MCP authorization spec, so compliant clients discover everything from the server URL:

1. The client calls https://freshlycited.com/mcp without a token and gets 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp", scope="mcp".
2. It reads the protected resource metadata (RFC 9728), which names FreshlyCited as the authorization server.
3. It reads the authorization server metadata (RFC 8414).
4. It identifies itself with a Client ID Metadata Document (an https client_id URL) or registers through dynamic client registration at /oauth/register (RFC 7591).
5. It sends you to /oauth/authorize with PKCE S256 and resource=https://freshlycited.com/mcp (RFC 8707).
6. You sign in with your normal FreshlyCited login and see the consent screen: pick the workspace and the access level.
7. The client exchanges the code at /oauth/token and calls the MCP server with Authorization: Bearer fca_….

Scopes

Tokens

• Access tokens (fca_…) last 1 hour and only work on /mcp; they're bound to that resource and rejected by the REST API.
• Refresh tokens (fcr_…) last 30 days and rotate on every use. If an old refresh token is used again, the whole connection is revoked for safety.
• The authorization response includes iss (RFC 9207). Redirect URIs must match exactly, except loopback URIs (http://127.0.0.1 / localhost), where the port may differ.
• Revoke with POST /oauth/revoke (RFC 7009), or disconnect the app under API keys › Connected apps. Removing you from the workspace also cuts the connection off.

Errors