Authentication
Clevername supports browser sessions, MCP OAuth for IDE clients, Hub Core API keys for internal services, and gateway tokens for fallback programmatic access.
Authentication methods
| Method | Header | Format | Use Case |
|---|---|---|---|
| Supabase JWT | X-Supabase-JWT | JWT token | Browser sessions, user-context requests |
| Hub Core API Key | Authorization | Bearer token | Server-to-server, internal services |
| MCP OAuth | OAuth 2.1 / PKCE | Browser sign-in | IDE clients and MCP tools via the gateway |
| Gateway Token | Authorization | Bearer cn-live-* (legacy cnk_* accepted) | Fallback programmatic access, raw HTTP, legacy MCP clients |
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
- Session-JWT failures return 401; gateway-token failures (invalid, expired, revoked, out of scope) return 403
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.
Use MCP OAuth for IDE clients
For MCP-compatible IDEs, add https://clevername.net/api/hub/mcp/gatewayand let the client open a browser login flow automatically.
Use a gateway token when OAuth is unavailable
For raw HTTP integrations or older MCP clients, create a gateway token in Dashboard → Settings → Keys and include it in the Authorization header:
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.
- 403 — 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.
- 403 — the agent behind the token is paused or suspended. Reactivate it in the dashboard.