Low Level Design: API Key Rotation Service

API key rotation is a security control that limits the blast radius of a leaked credential. A well-designed rotation service lets clients migrate to new keys without downtime by maintaining a short dual-active window. Below is a concrete low-level design covering schema, key generation, rotation workflow, expiry, audit logging, and emergency revocation.

API Key Schema

Each key row stores the hash, never the plaintext. A short prefix is stored in clear text so support staff and dashboards can identify a key without exposing it.

CREATE TABLE api_keys (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key_hash    CHAR(64) NOT NULL UNIQUE,   -- SHA-256 hex of the raw key
  prefix      VARCHAR(8) NOT NULL,        -- e.g. "sk_live_ab"
  owner_id    UUID NOT NULL REFERENCES users(id),
  scope       ENUM('read','write','admin') NOT NULL DEFAULT 'read',
  status      ENUM('active','grace','expired','revoked') NOT NULL DEFAULT 'active',
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  expires_at  TIMESTAMPTZ,
  last_used_at TIMESTAMPTZ
);

Scopes follow least-privilege: read allows GET requests only, write allows mutations, admin allows key management operations. The scope column is checked on every authenticated request, not just at issuance.

Key Generation

• Generate 32 cryptographically random bytes using CSPRNG (e.g. crypto/rand in Go, secrets.token_bytes(32) in Python).
• Base64url-encode the bytes to produce a 43-character URL-safe string. Prepend a typed prefix such as sk_live_ for production keys.
• Hash the full string with SHA-256 and store only the hash. Return the plaintext to the caller exactly once — it is never stored and cannot be recovered.
• Store the first 8 characters as prefix for display in dashboards and logs.

On every inbound API request, hash the provided key with SHA-256 and look it up in the api_keys table. Reject keys with status IN ('expired', 'revoked') immediately. Update last_used_at asynchronously (fire-and-forget write or a buffered batch) to avoid adding latency to the hot path.

Rotation Workflow

Rotation follows a three-phase process designed to give clients time to update their configurations without any interruption:

1. Issue new key. Create a new api_keys row with status = 'active'. Return the plaintext to the owner. The old key remains active — both keys are valid simultaneously.
2. Dual-active grace period. The old key transitions to status = 'grace'. It is still accepted for authentication but flagged in logs. The default grace period is 7 days, configurable per owner.
3. Expiry. After the grace period, a scheduled cleanup job sets old keys to status = 'expired'. Requests using expired keys receive HTTP 401 with a descriptive error pointing to the key prefix so the client knows which key to replace.

Automatic Expiry and Scheduled Cleanup

A background job runs every hour and executes:

UPDATE api_keys
SET status = 'expired'
WHERE status = 'grace'
  AND expires_at < now();

Keys can also carry an absolute expires_at regardless of rotation — useful for short-lived service tokens. The same cleanup job handles both cases in one pass.

Audit Log

Every lifecycle event writes a row to api_key_audit_log: key creation, rotation initiated, grace period started, expiry, and revocation. Each row records the key prefix (not the hash), the actor user ID, the IP address, and a timestamp. The audit log is append-only — rows are never updated or deleted — and is the source of truth for compliance reporting.

Emergency Revocation

A POST to /admin/api-keys/{id}/revoke immediately sets status = 'revoked' and writes an audit entry with the reason. Because authentication checks the database on every request, revocation takes effect within milliseconds — no cache TTL to wait out. If a distributed cache sits in front of the DB lookup, the revocation endpoint must also delete the cache entry by key hash. Revoked keys are retained in the table permanently for audit purposes.

Interview Talking Points

• Why store a hash and not the key itself? Breach of the keys table does not expose usable credentials.
• Why a typed prefix (sk_live_, sk_test_)? Enables secret scanning tools (e.g. GitHub secret scanning) to detect accidental commits.
• How do you handle a client that never rotates? Set a hard maximum lifetime policy (e.g. 1 year) enforced at issuance via expires_at = now() + interval '365 days'.
• How do you make revocation instant with a cache? Store a revocation bloom filter in Redis, updated on every revoke call, checked before the DB hit.

{ “@context”: “https://schema.org”, “@type”: “FAQPage”, “mainEntity”: [ { “@type”: “Question”, “name”: “What is an API key rotation service and why is it needed?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “An API key rotation service automates credential lifecycle management: generating keys, transitioning clients without downtime, and revoking compromised keys. It limits blast radius of leaked keys, enforces rotation schedules, and integrates with secrets managers to inject fresh credentials transparently.” } }, { “@type”: “Question”, “name”: “How does the grace period mechanism work during key rotation?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “After generating a new key, mark the old key PENDING_EXPIRY with a grace_expires_at timestamp. Accept both keys during the grace window. After grace_expires_at, mark the old key REVOKED. Tune the window to the slowest expected client refresh cycle.” } }, { “@type”: “Question”, “name”: “How do you store API keys securely without storing plaintext?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “Generate a cryptographically random key, store only an HMAC-SHA256 or Argon2id hash, show the plaintext only once at creation, and store a short prefix for UI identification. On inbound requests, hash and compare in constant time to prevent timing attacks.” } }, { “@type”: “Question”, “name”: “How do you handle emergency key revocation?”, “acceptedAnswer”: { “@type”: “Answer”, “text”: “Mark the key REVOKED in the database, publish a key.revoked event to Kafka or Redis Pub/Sub, and have auth service instances update their in-process revocation cache in real time (push-based) rather than waiting for TTL expiry. Simultaneously notify the owner and optionally issue a replacement key.” } } ] }

See also: Stripe Interview Guide 2026: Process, Bug Bash Round, and Payment Systems

See also: Netflix Interview Guide 2026: Streaming Architecture, Recommendation Systems, and Engineering Excellence

See also: Atlassian Interview Guide