# Authenticating an external caller

URL: https://kywi-docs-production.up.railway.app/integrating/authenticating-an-external-caller
Type: docPage

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.

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.

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

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.

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

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

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.

## A missing or malformed credential is a 401, not a 403

No header, a header that is not `Bearer …`, an unknown key, or a key whose owner has been deactivated all resolve to no user, and the route answers `{"error":{"code":"UNAUTHORIZED","message":"Unauthorized"}}`. A 403 means you authenticated and the role you resolved to was not enough — for a key, usually the scope ceiling rather than the owner's role.

## 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](/governing/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](/integrating/topologies-that-work--and-the-cross-origin-wall/).
