Authentication

Every request to https://api.forktime.ai/mcp carries a bearer token. The server accepts three kinds and resolves the caller’s brands + scopes from whichever it recognises.

OAuth 2.1 (connectors)

For clients that run a browser flow — claude.ai, Cursor, Claude Desktop. This is the recommended path for interactive use.

Forktime is a self-hosted OAuth 2.1 authorization server with discovery, PKCE (S256), dynamic client registration, and refresh-token rotation. Clients discover everything from the endpoint:

GET https://api.forktime.ai/.well-known/oauth-protected-resource
GET https://api.forktime.ai/.well-known/oauth-authorization-server

You don’t configure any of this by hand — add the connector and approve the sign-in. See Connect a client.

The issued access token is brand-scoped and carries the scopes you approved. Refresh tokens rotate (single-use) per the OAuth 2.1 spec.

API keys

For Claude Code, servers, and scripts — a static bearer token, no browser flow.

Keys look like gfk_live_… (or gfk_test_… outside production). Create and manage them in the dashboard → API keys — full walkthrough in Create an API key. When you create one you choose:

• the brands the key can access, and
• the scopes it’s allowed to use.

Authorization: Bearer gfk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Caution

The plaintext key is shown once at creation and never again — only a prefix + a hash are stored. Save it somewhere safe. Revoke and re-issue if it leaks.

A key’s brand access is fixed at issuance — it can’t be widened at call time by a header.

Dashboard sessions (JWT)

Our own dashboard and Front-of-House apps authenticate with a normal session JWT and send an X-Brand-Slug header to pick the active brand. Membership is checked against the brand’s team. This mode grants the signed-in user’s full access; it’s not something external developers use directly.

Which should I use?

You are…	Use
Adding a connector in claude.ai / Cursor	OAuth — just add the URL
Wiring Claude Code, a cron job, or a backend	API key (gfk_)
Building inside the Forktime dashboard	dashboard JWT

Whatever the mode, the server resolves the same { brands, scopes } context, so per-tool scope checks behave identically. A 401 means the token wasn’t accepted; a “not permitted” tool error means the token is valid but missing that scope.