Auth & API keys

401 AUTHENTICATION_REQUIRED#

No or invalid token. Re-login (JWT) or check that your key isn't revoked (API key — its is_active is false).

401 INVALID_API_KEY#

The key was revoked or doesn't exist. Re-issue in admin → /api-keys.

403 PERMISSION_DENIED#

The principal doesn't hold the required permission. Read the details.required_permission field and grant it via a role.

403 SCOPE_DENIED#

The API key's scopes array doesn't permit the action on this namespace/version/path. The message says exactly what it tried.

Fix: re-issue the key with a wider scope (e.g. drop the :namespace qualifier) or grant it the specific qualifier you need.

403 on a restricted namespace I "should" be able to read#

The namespace has visibility=restricted and you don't hold one of the read_role_slugs. In admin: Roles → make sure your user (or one of their groups) has the right role.

"Login works in admin but delivery says I'm anonymous"#

Delivery uses the docs session cookie, set when you POST to /docs/login. Admin uses a JWT in localStorage. They're separate.

Sign in at /docs/login?next=… on the delivery domain. The cookie is HttpOnly and SameSite=Lax; check your browser's storage to confirm it landed.