Skip to main content

Authentication

Clevername supports browser sessions, gateway tokens (cn-live-*) for IDEs, MCP clients and programmatic access, and Hub Core API keys for internal services.

Key Concepts

Authentication methods

MethodHeaderFormatUse Case
Supabase JWTX-Supabase-JWTJWT tokenBrowser sessions, user-context requests
Hub Core API KeyAuthorizationBearer tokenServer-to-server, internal services
Gateway TokenAuthorizationBearer cn-live-* (legacy cnk_* accepted)IDE and MCP clients via the gateway, raw HTTP, programmatic access

How auth flows work

Browser requests include the Supabase JWT automatically via cookies. The Vercel proxy at/api/hub/[...path] extracts the JWT, attaches a GCP identity token, and forwards the request to Hub Core. Hub Core resolves the user identity from the JWT and processes the request.

Security considerations

  • Never expose API keys or gateway tokens in client-side code
  • Gateway tokens have 90-day expiry and scoped permissions
  • MFA is required to create or delete API keys and tokens
  • Turning your own MCP servers on or off for an agent needs an MFA-verified session or a personal (not agent) gateway token, so it works headless. A service key acting on behalf of a user cannot do it.
  • Session-JWT failures return 401. A missing, invalid, expired or revoked gateway token returns 401 on the MCP gateway (/mcp/gateway) and 403 on the REST API; a valid token that is not allowed (out of scope) returns 403 on both
Step-by-Step Guide
1

Get your Supabase JWT (browser)

For browser-based integrations, sign in through the Clevername dashboard. The JWT is set automatically as a session cookie. The Vercel proxy reads this cookie and attaches it to API requests.

Note
You do not need to manually extract or pass the JWT for browser requests. The dashboard handles this automatically.
2

Use a gateway token for IDE, MCP, and HTTP clients

Create a cn-live-* key at Settings → Keys → Personal Access Keys and include it in the Authorization header. IDEs and MCP clients send it to https://clevername.net/api/hub/mcp/gateway (client snippets: IDE Gateway). OAuth sign-in for MCP clients is coming.

Authorization: Bearer cn-live-your_token_here
3

Handle auth errors

Auth failures return a JSON body whose detail field describes the problem in plain text (there are no machine-readable error codes). Branch on the status code, not the message — which one you get depends on the credential, not the cause:

  • 401 — the browser session JWT is expired, malformed, or revoked. Sign in again.
  • 401 (MCP gateway) — the gateway token is missing, invalid, expired, or revoked (“Invalid or expired MCP access token”). Create or copy a token.
  • 403 (REST API) — the gateway token is invalid, expired, or revoked (“Invalid or expired gateway token”). Create a new token.
  • 403 — the token is valid but lacks the scope the endpoint needs (“Insufficient gateway token scope: requires ‘mcp’”).
  • 403 — the operation requires an MFA or passkey step-up the session has not completed. Key and token management is browser-session-only.
  • The agent behind the token is paused, suspended, or pending review: the request is refused and the message says which. Reactivate the agent, or wait for its review, in the dashboard.