Platform & API Product Engineering · Lesson 06

Developer Platform: Apps, Keys, Scopes & Rotation

One key per user is an anti-pattern. Real developer platforms issue credentials to applications, not accounts — enabling blast-radius isolation, independent rotation, and precise attribution. This lesson covers every layer of that model, from the bit layout of a key to the database schema behind zero-downtime rotation.

The platform model: apps own credentials, accounts own apps

Most internal APIs start with a simple model: one API key per team, per user, or per environment. That works until it doesn't. When a key leaks, you have to rotate everything. When a key is misused, you can't tell which integration did it. When a contractor leaves, you can't revoke only their access.

Developer platforms — Stripe, HubSpot, GitHub, AWS — solved this by introducing an intermediate entity: the App. An App represents a specific integration: a webhook listener, a billing sync, a data pipeline. Each App gets its own credentials, its own scopes, its own rate-limit tier, and its own webhook endpoints. A single account can have many apps.

This hierarchy gives you three things "one key per account" cannot:

• Attribution. Every API call is tagged to a specific app. When something goes wrong, you know which integration caused it — not just "someone with an account key did this."
• Blast-radius isolation. A leaked key for the billing-sync app only exposes billing scopes. The webhook-relay app's credentials are unaffected.
• Independent rotation. You can rotate keys for one app without touching any other. No coordinated outage, no "tell every team to update their .env" scramble.

Key format: what's inside sk_live_3xKj9mRpQ…

An API key is not just a random string. A well-designed key encodes enough structure to be useful without leaking secrets.

The prefix-first design also enables a critical defensive property: secret scanning. GitHub, GitLab, and dozens of third-party tools scan public repositories for strings matching known key prefixes. If a developer accidentally commits sk_live_3xKj9mRp…, the scanner matches sk_live_ and alerts within minutes. Without a recognizable prefix, the key is invisible to scanners — it looks like any other long random string.

Entropy: why 128 bits is the floor

A 32-byte CSPRNG output gives 256 bits of entropy. Encoding that as base58 produces ~44 characters; base64url gives ~43 characters. Either is fine. The question is why 128 bits is treated as the minimum acceptable floor.

At 128 bits, the key space contains 2¹²⁸ ≈ 3.4 × 10³⁸ possible keys. Assuming an adversary can check 10⁹ guesses per second — an extremely generous assumption given that each guess requires a database lookup — brute-forcing would take approximately 10²² years. For reference, the age of the universe is ~1.4 × 10¹⁰ years. This is a modeled bound, not a proof of security, but it establishes that the attack surface for brute force is not the key's randomness; it's everything else (social engineering, key exposure via logs, insecure storage).

Hashing at rest: SHA-256, not bcrypt

Both passwords and API keys should be hashed before storage. But the right hash function is different for each, and the reasoning matters.

Passwords have low entropy — humans choose them, so they cluster around common patterns. bcrypt, scrypt, and Argon2 are designed to be slow, making brute-force attacks against a stolen hash database expensive. The slowness is the feature.

API keys have high entropy by construction — 32 bytes of CSPRNG output. An attacker who steals a hash database cannot brute-force a 256-bit key space. bcrypt's slowness is therefore irrelevant as a defense, but it is very relevant as a cost: every API request would require a bcrypt lookup, adding 50–200ms of latency per call. SHA-256 takes microseconds. The protection comes from entropy, not hash slowness.

In practice, many platforms use HMAC-SHA256(key, server_secret) rather than bare SHA-256. The server secret (stored separately from the database, e.g., in a secrets manager) means that even if the hash database is exfiltrated, an attacker still needs the server secret to compute valid HMAC inputs. This adds a second factor without meaningful performance cost.

The show-once rule: minting a key

The full key is shown to the developer exactly once: at creation. From that moment, the platform only has the hash. It cannot show the key again even if asked. This is not a UX decision — it's a security requirement. If the platform could retrieve the full key on demand, then an XSS attack on the developer dashboard, a compromised admin session, or a database query by a rogue employee could expose every key to every customer.

Complete pseudocode: minting and verifying

Here is the complete flow — issuance and verification — precise enough to implement directly:

# Key creation — called when a developer clicks "Create new API key"
function create_api_key(app_id, scopes):
    raw_random   = crypto.randomBytes(32)           # 256 bits of CSPRNG
    prefix       = "sk_live_"
    key_body     = base58encode(raw_random)           # ~44 chars, URL-safe
    full_key     = prefix + key_body                  # e.g. sk_live_3xKj9mRpQf…

    key_hash     = SHA256(full_key)                   # this is stored
    display_hint = full_key[:12]                     # e.g. "sk_live_3xKj" — safe to show

    DB.insert({
        app_id:       app_id,
        key_hash:     key_hash,        # ONLY this — never full_key
        display_hint: display_hint,    # first 12 chars for dashboard identification
        scopes:       scopes,
        created_at:   now(),
        expires_at:   now() + 90_days, # optional TTL; null = never expires
        revoked:      false
    })

    return full_key   # shown ONCE to developer; server discards it immediately after

# Request verification — called on every inbound API request
function verify_request(authorization_header):
    raw_key  = strip_bearer(authorization_header)     # e.g. "sk_live_3xKj9…"

    # Basic prefix sanity-check (fast rejection before DB lookup)
    if not raw_key.startsWith("sk_live_") and not raw_key.startsWith("sk_test_"):
        return 401

    key_hash = SHA256(raw_key)                        # recompute hash
    record   = DB.lookup_by_hash(key_hash)            # single indexed lookup

    if not record:
        return 401   # key doesn't exist
    if record.revoked:
        return 401   # key has been revoked — don't hint which
    if record.expires_at and record.expires_at < now():
        return 401   # key expired

    # Attach identity context for downstream scope checks
    return {
        app_id: record.app_id,
        scopes: record.scopes,
        env:    parse_env(raw_key)  # "live" or "test" from prefix
    }

Scoped keys: least privilege per integration

Every key carries a set of permission scopes. The scope set is stored with the key record in the database and returned on every successful key lookup. Authorization is checked against that set, never against account-level permissions.

Scope design conventions that appear across real platforms:

• read:resource / write:resource — the colon-separated format makes scope prefix-matching easy: "read:" can be checked as a prefix filter for all read scopes.
• admin:resource — a higher-tier scope that implies both read and write, plus management operations (delete, configure).
• Scopes are explicit grants, not inherited by default. A key without read:invoices cannot read invoices, even if the account has that permission. The key is the scope boundary.

How the middleware checks scopes on every request

1. Authentication middleware extracts the key from the Authorization header, hashes it, looks up the record, returns { app_id, scopes } or 401.
2. Route handler declares the required scope(s) — e.g., required_scope = "write:invoices".
3. Authorization middleware checks whether required_scope ∈ context.scopes. If not: 403 Forbidden.
4. Business logic proceeds, with context.app_id available for attribution and audit logging.

The 403 response reveals the required scope explicitly. This is intentional — the caller is authenticated (the key is valid), so there's no oracle risk in telling them which permission is missing. The alternative — a vague "access denied" — makes debugging unnecessarily painful.

Compare to the 401 case: when the key itself is invalid or expired, the response is deliberately uninformative. Telling an anonymous caller "your key is revoked" versus "your key doesn't exist" would reveal whether a guessed key is a valid (revoked) credential — a subtle oracle. Both cases return the same message.

Key lifecycle: issuance to decommission

A key's lifecycle has five distinct phases. Each requires a deliberate decision — get any of them wrong and you either create downtime (bad rotation design), security exposure (no expiry or revocation), or operational friction (no leak detection).

a. Issuance

Developer creates an app → selects scopes → clicks "Create key." Platform generates the key (CSPRNG → prefix + body), stores only the hash and display hint, and shows the full key exactly once in a modal with a "Copy" button. The modal carries a warning: "This key will not be shown again. Store it securely." The developer closes the modal. The key is gone from the server's memory.

b. Rotation without downtime — the dual-key overlap window

This is the most operationally important design decision in key lifecycle management. Naive key rotation — revoke old, create new, update config — has a mandatory downtime window between step 1 and step 3. The correct approach is an overlap window:

1. Developer creates a new key (Key B). Both Key A and Key B are now valid. The platform supports multiple active keys per app simultaneously.
2. Developer updates their application's configuration to use Key B. This is deployed to production — could be immediate, could take 24–72 hours across multiple regions and services.
3. Developer verifies that Key B is receiving traffic (check the platform's per-key request logs).
4. Developer retires Key A via the dashboard. It is immediately revoked — all subsequent requests using Key A receive 401.

The overlap window length should match your deployment cycle. If your services can be updated in under an hour, a 24-hour overlap gives 24× headroom. Most platforms support 2–5 simultaneous valid keys per app — enough for rotation without becoming an unmanaged proliferation risk.

c. Revocation

Revocation is immediate and unconditional. The platform sets revoked = true on the key record. The next request using that key gets 401 — there is no grace period. This is why the overlap window happens before revocation, not after. You never revoke first.

Revocation is surfaced in the audit log with: timestamp, who triggered it (user/system/leak-detection), and the key display hint. The full key is never logged — only the hint and hash.

d. Expiry (TTL keys)

Keys can carry an optional expires_at timestamp. When set, the verification path checks expires_at < now() before allowing the request. Expired keys return 401 with a message that distinguishes expiry from revocation — developers need to know whether to rotate or investigate.

Compliance use cases typically mandate 90-day expiry. Developer tools (CI tokens, local dev keys) can use shorter TTLs (24 hours or 7 days) to bound exposure. Long-lived production service keys can be issued without expiry, relying on explicit rotation policies instead.

e. Leak detection

GitHub's secret scanning API notifies registered platforms when a commit or public gist contains a string matching the platform's key pattern. This requires registering your key prefix pattern with GitHub's secret scanning partner program. When a match is found:

1. GitHub sends a webhook to the platform's leak-detection endpoint with the raw matched key.
2. Platform hashes the leaked key, looks it up in the database.
3. If found and not already revoked: auto-revoke, send email/notification to the key owner, log the incident.
4. Platform sends a confirmation response to GitHub within 5 seconds — required by the protocol.

The response to the developer should be specific: "Your key sk_live_3xKj… was found in a public repository at [URL] and has been automatically revoked. Create a new key and ensure it is not committed to version control."

Per-app configuration beyond keys

The App entity is the configuration boundary for everything about an integration, not just keys:

API key vs OAuth token: choosing the right tool

These are not competing credentials — they solve different problems. The mistake is using one where the other is clearly right.

The principle is simple: if a human user's permission is required, use OAuth. If the integration is purely machine-to-machine, use an API key. Stripe's payment processing API uses keys — no user is "delegating" access; you're calling Stripe on behalf of your platform. GitHub's user API uses OAuth — a third-party app needs a specific user's permission to read their repositories.

Trade-off tables

Long-lived vs short-lived keys

One account-wide key vs per-app keys

Prefix routing: benefits vs complexity

How real platforms do it

Every major developer platform has converged on the app model, each with slight variations that reflect their specific threat model and developer experience choices.

Note the convergence: all four platforms have moved toward shorter-lived, narrower-scoped credentials and away from long-lived, broad-access keys. GitHub deprecated classic PATs. HubSpot deprecated the hapikey pattern. AWS pushes IAM roles with STS over long-lived IAM user keys. The direction of travel is clear.

For complementary coverage of key security from the threat and hardening angle — JWT pitfalls, the bcrypt vs SHA-256 tradeoff in depth, and the OWASP hardening checklist — see Lesson sec-08: API Keys, JWTs & a Hardening Checklist.

By the numbers

Quiz

-- Accounts: the billing/ownership entity
CREATE TABLE accounts (
    id          UUID          PRIMARY KEY DEFAULT gen_random_uuid(),
    name        VARCHAR(255)  NOT NULL,
    created_at  TIMESTAMPTZ   DEFAULT now()
);

-- Apps: one per integration, owned by an account
CREATE TABLE apps (
    id              UUID          PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id      UUID          REFERENCES accounts(id) ON DELETE CASCADE,
    name            VARCHAR(100)  NOT NULL,
    granted_scopes  TEXT[]        NOT NULL DEFAULT '{}',
    environment     VARCHAR(10)   NOT NULL DEFAULT 'test',  -- 'live' | 'test'
    created_at      TIMESTAMPTZ   DEFAULT now()
);

-- API keys: multiple per app, only hash stored
CREATE TABLE api_keys (
    id           UUID          PRIMARY KEY DEFAULT gen_random_uuid(),
    app_id       UUID          REFERENCES apps(id) ON DELETE CASCADE,
    key_hash     CHAR(64)       NOT NULL UNIQUE,   -- SHA-256 hex; the only secret-derived value stored
    display_hint VARCHAR(16)   NOT NULL,          -- e.g. "sk_live_3xKj" — first 12 chars
    scopes       TEXT[]        NOT NULL,          -- subset of app.granted_scopes
    revoked      BOOLEAN       NOT NULL DEFAULT FALSE,
    revoked_at   TIMESTAMPTZ,
    revoked_by   VARCHAR(50),                     -- 'user', 'leak_detection', 'expiry_job'
    expires_at   TIMESTAMPTZ,                      -- NULL = no expiry
    created_at   TIMESTAMPTZ   DEFAULT now(),
    last_used_at TIMESTAMPTZ                       -- updated async; useful for key hygiene
);

-- Index for fast hash lookup on every request
CREATE INDEX idx_api_keys_hash ON api_keys(key_hash) WHERE NOT revoked;

Sources & further reading

• Stripe — API Keys documentation (restricted keys, test vs live)
• GitHub — Managing personal access tokens (fine-grained PATs)
• HubSpot — Private Apps and access tokens
• AWS IAM — Managing access keys for IAM users
• GitHub — Secret scanning partner program
• OWASP Authentication Cheat Sheet
• RFC 6749 — The OAuth 2.0 Authorization Framework