Authentication

There are two kinds of credential: user accounts (with a JWT from login) and API keys. Both are sent as Authorization: Bearer <credential>.

Users and roles

Users authenticate at /admin/login and receive a 12-hour JWT.

Role	Can do
`admin`	Everything, including managing content types, users, keys, and webhooks.
`editor`	Read and mutate any entry.
`author`	Read any entry; mutate only entries they created.

TOKEN=$(curl -s -X POST $B/admin/login \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' | jq -r .token)

Admins create more users at POST /admin/users.

API keys

API keys are for programmatic access, typically from a frontend. There are two roles:

read — read published entries (and non-public types).
write — read drafts and create, update, publish, and delete entries.

An admin creates keys at POST /admin/api-keys. The raw key is returned exactly once and stored only as a hash — save it immediately.

curl -s -X POST $B/admin/api-keys \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"name":"frontend","role":"read"}'

Self-service read keys

If the deployment has KEYGEN_PASSWORD set, anyone with that password can mint a read-only key at /keygen — a small web form, no admin login required. Write keys always require an admin.

curl -s -X POST $B/keygen -H 'content-type: application/json' \
  -d '{"password":"THE_KEYGEN_PASSWORD","name":"frontend"}'

The /keygen password is a shared secret. Anyone who has it can create read keys, so treat it accordingly and rotate it if it leaks. It can never create write keys.

Access summary

Caller	Read published	Read drafts	Mutate
anonymous	public types only	no	no
`read` key	all types	no	no
`write` key	all types	yes	any entry
`author` user	all types	yes	own entries
`editor` / `admin` user	all types	yes	any entry

​Users and roles

​API keys

​Self-service read keys

​Access summary

Users and roles

API keys

Self-service read keys

Access summary