---
summary: 401/403 errors and how to read them.
title: Auth & API keys
path: troubleshooting/auth-and-api-keys
status: published
---

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