One active key per database, on purpose

The model

Each database has at most one active API key. The key is bound to that database and carries one permission level: read-only or read-write. Creating a second active key for the same database returns 409 ERR_CONFLICT. Rotation is revoke, then mint.

The plaintext token is shown once at creation. The platform stores a hash and a short prefix for identification; it cannot recover the token later. Losing it means a rotation, not a lookup.

{
  "success": false,
  "error": {
    "code": "ERR_CONFLICT",
    "message": "This database already has an active API key"
  }
}

Why not many keys

Multiple keys per database are convenient, but they make revocation ambiguous. Which key is this service using? Which key leaked? Which key can be removed before the next deploy? A single active credential makes the answer concrete.

It also makes permission boundaries easier to reason about. If a database needs read-only and read-write callers, the clean split is two databases, not two credentials with different powers over the same data.

Rotation without downtime

Revocation is immediate: the next request with the old key fails with 401. To rotate safely, deploy code that can read the new token, revoke the old key, mint the replacement, then update the secret store and restart or reload the caller.

Because only one key can be active, a rolling deploy cannot have two valid generations at once. Plan the cutover as a short, explicit step rather than an accidental overlap.

• Store the plaintext in a server-side secret store, never in client code.
• Use read-only keys for reporting, dashboards and anything that only reads.
• Treat revocation as an incident response action: it is instant and irreversible.