Authenticating an external caller
Every caller authenticates through `Authorization: Bearer` — a session JWT, or a `kywi_` API key whose scopes cap the owner’s role for that request.
One header, two credential kinds. Kywi reads Authorization: Bearer <token> and branches on the prefix: a value starting kywi_ is looked up as an API key, anything else is verified as a session JWT. There is no x-api-key path: the server never reads that header, so a key sent on it authenticates as nobody.
curl -H 'Authorization: Bearer kywi_Kx8Qw2mB7vN4pR1sT6uY9zA3cE5gH0jL' \
'https://cms.example.com/api/v1/content/page?siteId=default'Scopes are a ceiling, not a grant
A key's scopes add no permissions. Each names the highest role it allows, and the request runs as whichever is lower: that ceiling, or the role of the key's owner. A key a superAdmin created with only read is a reader for every request it makes; a key scoped admin owned by an author is still an author.
deny rather than falling back to the owner.| Name | Type | Default | Description |
|---|---|---|---|
read | reader | — | Read published and draft content through the content routes. |
write | author | — | Create and update content — draft it, not publish it. |
publish | editor | — | Move content through the workflow into published. |
admin | siteAdmin | — | The admin-gated routes, including content deletion. |
developer | siteAdmin | — | The developer surfaces — plugins, extensions, content types. |
Creating a key
Key creation is session-only: the create route refuses any caller that authenticated with a key at all, because otherwise a read-scoped key could bootstrap an admin-scoped one and walk past the ceiling above. It checks only that a session resolved, not which role it holds — any signed-in session can create a key, whatever its own role is. What the new key can then do is still capped, both by the scopes you give it and by the creating account's own role. The two management routes carry no such rule and are scoped to the caller's own keys.
/api/v1/auth/api-keysAdmin sessionBody is { name, scopes }, where scopes is a
non-empty array drawn from the five values above — any other string fails validation
before a key exists. Refused with
403 {"error":{"code":"FORBIDDEN","message":"API keys cannot create API keys"}}
when the request itself authenticated with a key.
{
"data": {
"rawKey": "kywi_Kx8Qw2mB7vN4pR1sT6uY9zA3cE5gH0jL",
"row": {
"id": "5b0f2c9e-1d43-4a77-9c2e-3f8a1b6d0e47",
"userId": "c1a7d3f0-88b2-4e19-a5cc-72f4be901d33",
"name": "storefront-ssr",
"keyHash": "9c1f…",
"keyPrefix": "kywi_Kx8Qw2m",
"scopes": ["read"],
"lastUsedAt": null,
"createdAt": "2026-09-02T10:14:22.311Z"
}
}
}rawKey is the only field you cannot get back later: the key is stored as a SHA-256 hash and the plaintext is never persisted. The twelve-character keyPrefix — kywi_ plus seven characters — is how you identify a key in the list without holding it.
/api/v1/auth/api-keysBearer tokenThe caller's own keys, metadata only — this projection omits
keyHash. Other users' keys are not reachable through this route at all.
/api/v1/auth/api-keys/:idBearer tokenRevoke one of the caller's own keys. A key belonging to someone else
answers 404 "API key not found or not owned by you" rather than 403 — the
route does not confirm that the id exists.
Keys are exempt from the forced-password-reset gate
Every request carrying an Authorization header passes one gate before routing: a user flagged for a forced password reset is refused with a PASSWORD_RESET_REQUIRED code. Key-authenticated requests skip it — a key has no human to satisfy a reset, so gating it would take every agent, CI job and server-side frontend offline the moment an admin forced a reset on the key's owner. Revoking the key or deactivating its owner is the tool for freezing automation; both stop it immediately. SDK callers detect the gate with isPasswordResetRequiredError: it is a 403, but re-logging in will not clear it.
Sessions, and why an external caller never gets one
A signed-in browser on the Kywi app's own origin sends no Authorization header. Middleware bridges it: for /api/v1 requests carrying no header of their own, a valid access cookie is copied on as a bearer token, refreshed from the refresh cookie first if it has expired. That bridge belongs to the Kywi app's own middleware and to requests already holding its cookies, so an external caller holds a key instead.
For what the roles those ceilings name can actually do, see Roles and the capability matrix; for why the caller is a server rather than a browser, see Topologies that work — and the cross-origin wall.