API tokens

User-scoped API tokens let you call any /api/* endpoint from your own scripts without doing the JWT login dance. They're what powers Scribe, but you can issue your own for cron jobs, importers, dashboards, anything.

Format

Tokens look like tome_AbCdEf123…. The tome_ prefix is constant; the body is 32 random URL-safe bytes. Server-side, only the sha256 hash is stored — the secret itself is shown exactly once at creation time and never again.

Creating a token

1. Open Settings → API tokens.
2. Click New token, give it a name (so future-you remembers what it's for).
3. The full tome_… secret appears once. Copy it now.
4. Store it somewhere safe (a password manager, an env var, an .env file your VCS ignores).

Universal scope

A token authenticates as the user who created it. Every /api/* endpoint accepts either a JWT (from a logged-in browser) or a tome_… bearer token — they're interchangeable. There are no per-scope tokens (yet): an admin's token has admin powers, a guest's token has guest powers.

Using a token

Send it as a bearer token in the Authorization header. Examples in three flavours:

# Replace TOKEN with your tome_… secret
curl -H "Authorization: Bearer $TOKEN" \
     https://your-tome.example.com/api/books?limit=5

Revoking

In Settings → API tokens, find the token by name or prefix and click Revoke. The hash is deleted; any further calls with that secret 401 immediately. Revocation is irreversible.

Admin view

Admins can see — and revoke — every user's tokens from Admin → Users → [user] → Tokens. Useful when an account is compromised or a member leaves the household and you want to nuke their scripts. Admins cannot view the secret (it's only the hash) but they can kill it.