API keys

What a key is, and is not#

A key acts as its creating user, with exactly their access — every request re-runs the same membership, role and board-access checks your own session would.

• A key made by a viewer is read-only.
• If your role changes, your existing keys change with it, immediately.
• A key is confined to the one workspace you name when you create it.
• A key cannot mint further keys and cannot reach /profile, /admin, /billing, /notifications or /auth — only the board/ticket/wiki/search API.

Create a key#

The secret is shown once:

curl -X POST https://api.laver.app/profile/api-keys \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"workspace_uuid": "11111111-2222-4333-8444-555555555555", "name": "nightly triage bot"}'

Only a hash is stored server-side — lose it and you revoke, then make another.

Expiry#

Optional expires_at. Once passed, requests get 401 with "api_key_expired": true. For the last 14 days before expiry, successful responses carry x-api-key-expires-at so a script that never checks the admin panel still finds out in time.

Service accounts#

A personal key stops when its owner does — right for your own scripts, wrong for a team's build bot. A service account belongs to the workspace instead, is given explicit board access (no person to inherit from), and keeps working after the admin who created it leaves. It uses a seat, cannot hold a session, and cannot be promoted to admin.

Delete a key#

Revocation is immediate and irreversible — a new key with the same name does not restore access.

Ten keys per workspace#

The eleventh is refused with 409; revoked keys don't count.

If a key leaks#

1. Revoke it now.
2. Issue a replacement and deploy it — after revoking, not before.
3. Check what it could reach: a personal key's blast radius is its owner's role and boards inside that one workspace.
4. Check last_used_ip and the audit log for anything unfamiliar.
5. If you can't reach the owner, deactivate them in Admin → People — that stops every key they hold at once (not a service account, which has no owner to deactivate).
6. Scrub wherever it leaked, last.