API Keys #

Summary #

Admins issue API keys in the admin area. Each key has a label and a set of roles, and is sent as Authorization: Bearer <key>. A route opens itself to API keys by naming the roles it allows, and only those routes accept keys. The first such route is cron, from [[cron]].

Motivation #

Some server work has to be started from outside the browser, such as a crontab calling the server on a schedule. Those callers have no atproto account and no web session, so they need a credential an admin can issue and revoke without touching the server's environment or restarting it.

Design #

Keys #

api_key (id text primary key, label text, key_hash text unique, roles_json text, created_by text, created_at text, last_used_at text null)

• Format. A key is scn_ followed by 32 random bytes in base64url. It is shown once, when it is issued, and only its SHA-256 hash is stored. A key is random, so a fast hash is enough, and a key is found by looking up its hash.
• Roles. A key holds one or more existing roles, including the built-in user and admin. A key has no DID, so it holds only the roles it's given, and PDS host and handle domain matches don't apply to it.
• Changing a key. Keys can't be edited. To change a key's roles, issue a new one and revoke the old.
• Deleting a role that a key holds is refused, with the keys listed, like the other uses of a role in [[admin]].
• Last used. A successful request with a key records the time, so an admin can spot keys nobody uses.

Route access #

requireApiKey(...roles) is Hono middleware that opens a route to API keys:

• No Authorization: Bearer header, or a key that doesn't match, is a 401.
• A key that holds none of the route's roles is a 403.
• A route without requireApiKey never accepts a key, and a route with it never accepts a web session.

Keys never appear in logs. A rejected request logs the route and the reason, and an accepted one logs the key's label.

Admin API #

Route	Purpose
GET /api/admin/api-keys	Every key's ID, label, roles, creator, created time, and last use. Never the key or its hash.
POST /api/admin/api-keys	Issue a key from { label, roles }. Answers with { id, key }, the only time the key is returned.
DELETE /api/admin/api-keys/:id	Revoke a key.

Admin area #

API keys (/admin/api-keys): a table of keys with their label, roles, created time, last use, and a Revoke button, and a form with a label and a checkbox per role that issues a key and shows it once, with a note that it can't be shown again.

Documentation #

• CLAUDE.md and docs/architecture.md: the rule against a public HTTP API allows routes opened to API keys, currently cron.
• docs/deployment.md: issuing a key for cron.

Scope Boundaries #

• No keys acting as a user. A key has no DID and can't read or write chats.
• No keys on existing routes. Only routes that name roles with requireApiKey accept them.
• No expiry. A key lasts until it is revoked.
• No keys in .env or files. Keys are issued and revoked in the admin area, apart from the single-use keys the site-config CLI issues itself and revokes, from [[site-config]].

Edge Cases and Decisions #

• Keys are compared by hash lookup, so there is no timing difference to measure between keys.

Acceptance Criteria #

• Issuing a key returns it once, and only its hash is stored.
• A route opened to a role accepts a key holding that role.
• A missing or unknown key is a 401, and a key without the route's roles is a 403.
• A revoked key is a 401.
• A route not opened to keys doesn't accept one, and a key route doesn't accept a web session.
• Issuing a key with a role that doesn't exist is refused.
• Deleting a role a key holds is refused, listing the keys.
• The key list never contains a key or its hash.
• A successful request records the key's last use.

Files #

• apps/server/src/auth/api-keys.ts
• apps/server/src/admin/routes.ts
• apps/server/src/db/migrations/
• apps/web/src/features/admin/, apps/web/src/routes/_app/admin/
• CLAUDE.md, docs/architecture.md, docs/deployment.md