Authentication
Keel has separate credentials for runtime calls, dashboard management, and approval. Do not substitute one class for another.
Runtime API keys
Send a project API key as a Bearer token:
Authorization: Bearer keel_sk_...Project API keys are scoped to one project. If a request body also contains
project_id, it must match the authenticated key’s project. X-API-Key is
accepted on documented compatibility paths, but Bearer authentication is the
public contract for new integrations.
Project keys have three scopes:
| Scope | Intended use |
|---|---|
client | Runtime decision and managed-execution requests that accept a project API key. |
admin | Project-scoped administrative runtime operations, including routes explicitly labeled admin-scope. Do not put this key in client-side code. |
approval | Service-principal approval of a review requirement. It is not a general execution credential. |
The generated public route table is the source for each route’s exact authentication class. A route labeled Project API key with admin scope must not be called with a client key. Routes labeled Project API key or approval key still authorize the specific operation; possessing either credential is not blanket approval authority.
Dashboard sessions
Management routes use an authenticated user session or verified user JWT. They back the dashboard and include project, policy, provider-key, billing, and API-key management. Do not automate dashboard cookies as if they were runtime API keys.
Public and special-purpose routes
Some status and verification-key routes are unauthenticated. Exact Permit guest flows, invitation flows, and Stripe webhooks use route-specific cookies, tokens, origin checks, or signatures. Their presence does not make neighboring routes public.
Secret handling
- Create and revoke credentials in the dashboard or documented management flow.
- Store runtime keys in a secrets manager or server-side environment variable.
- Never commit keys, paste them into agent prompts, or expose them in browser bundles, client logs, screenshots, or support transcripts.
- Use the narrowest scope that satisfies the route.
- Treat a copied key as compromised and revoke it.
- Provider credentials used by Keel-managed dispatch remain server-side. A permit-first integration instead owns and protects its provider credential.
Authentication failures
401means the credential is missing, invalid, expired, or otherwise not authenticated. Fix authentication before retrying.403can mean the credential is authenticated but lacks the required scope, targets the wrong project, or is not authorized for the operation. Do not retry unchanged.- Execution routes can additionally require request-freshness headers. Passing authentication does not bypass freshness validation.