Skip to content

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.

bash
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.

The five accepted scope values and the role each ceilings at. Several scopes take the highest ceiling among them, not the sum. No scope reaches superAdmin, so superAdmin-only operations always need a session — and an empty or unrecognized scope list resolves to deny rather than falling back to the owner.
NameTypeDefaultDescription
readreader—
Read published and draft content through the content routes.
writeauthor—
Create and update content — draft it, not publish it.
publisheditor—
Move content through the workflow into published.
adminsiteAdmin—
The admin-gated routes, including content deletion.
developersiteAdmin—
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.

POST/api/v1/auth/api-keysAdmin session

Body 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.

201
{
  "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.

GET/api/v1/auth/api-keysBearer token

The caller's own keys, metadata only — this projection omits keyHash. Other users' keys are not reachable through this route at all.

DELETE/api/v1/auth/api-keys/:idBearer token

Revoke 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.