Writing API Key Code for Your Own Service With LLMs in November 2026: Show the Key Once, Store Only a Hash, and Make Rotation Painless

If your product has an API, sooner or later customers will ask for API keys so their scripts and servers can call it without a browser login. Ask an LLM to "add API key authentication" and you will usually get something that works on the first request: a random string, a column in the users table, and a middleware that compares the header to that column. It also tends to store keys in plain text, compare them in a way that leaks timing, give every key full access, and offer no way to rotate a key without breaking the customer's integration.

This post walks through what a solid API key system for your own service looks like, how to prompt for it, and what to check in the code you get back. The examples use Python and PostgreSQL, but the ideas carry over to any stack.

A key cutting machine

Anyone can cut a copy of a physical key. Make sure your API keys cannot be copied out of your database. Image: Key cutting machine by Fumikas Sagisavas, CC0, via Wikimedia Commons.

Decide what an API key is in your system before you prompt

Most bad generated code comes from a vague request. Before you open the chat, write down answers to these questions and paste them into the prompt:

  • Who owns a key? A user, an organization or workspace, or a service account. If customers have teams, keys almost always belong to the organization, with a record of which user created them.
  • How many keys can an owner have? Allow more than one. Rotation without downtime requires at least two keys to be valid at the same time.
  • What can a key do? Full access, read-only, or a list of named scopes such as orders:read and orders:write.
  • Do keys expire? Optional expiry dates are cheap to add now and painful to retrofit later.
  • Test and live modes? If you have a sandbox environment, keys should say which one they belong to.

A prompt that includes these decisions, plus your framework, database, and the existing user and organization tables, gets far better output than "add API keys."

Generate keys with a secure random source and a readable prefix

The key itself should come from a cryptographically secure random generator, not from random, a UUID version 1, a timestamp, or a hash of the user ID. In Python that means the secrets module. 32 random bytes (256 bits) is plenty.

Add a short, fixed prefix that identifies the key type, and a separate public identifier that lets you look the key up without scanning the whole table. A common shape is:

tn_live_7Kq2XbP9_wE3r...long-random-secret...
^^^^^^^ ^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
prefix  key id   secret

The prefix helps in three ways. Humans can tell at a glance what kind of credential they are holding. Your support team can ask "what does the key start with?" without seeing the secret. And secret scanners, including the ones built into code hosting platforms, can match a distinctive prefix when someone accidentally commits a key to a public repository. A generic 40-character hex string looks like any other hash and is hard to flag.

import secrets

def new_api_key(mode: str = "live") -> tuple[str, str, str]:
    key_id = secrets.token_urlsafe(6)      # short, public, used for lookup
    secret = secrets.token_urlsafe(32)     # 256 bits, never stored in plain text
    full_key = f"tn_{mode}_{key_id}_{secret}"
    return full_key, key_id, secret

Watch for generated code that uses uuid.uuid4() as the whole key. It is random, but it gives you less entropy than you might think and no prefix. Also watch for random.choice loops, which are not suitable for secrets.

Store only a hash, and show the key exactly once

An API key is a password that a machine types. If your database leaks, plain-text keys let an attacker call your API as every customer. Store a hash instead and show the full key to the user only once, at creation time, with a clear message that it cannot be shown again.

Unlike user passwords, API keys are long and fully random, so you do not need a slow password hash such as bcrypt or Argon2. Those are designed to slow down guessing of short human passwords, and running one on every API request would add real latency. A fast keyed hash is the usual choice: HMAC-SHA-256 with a server-side secret (often called a pepper) that lives in your secrets manager, not in the database.

import hmac, hashlib

def hash_secret(secret: str, pepper: bytes) -> str:
    return hmac.new(pepper, secret.encode(), hashlib.sha256).hexdigest()

A reasonable table looks like this:

CREATE TABLE api_keys (
  id            bigserial PRIMARY KEY,
  key_id        text NOT NULL UNIQUE,
  secret_hash   text NOT NULL,
  org_id        bigint NOT NULL REFERENCES organizations(id),
  created_by    bigint REFERENCES users(id),
  name          text NOT NULL,           -- "CI pipeline", "billing sync"
  mode          text NOT NULL CHECK (mode IN ('live', 'test')),
  scopes        text[] NOT NULL DEFAULT '{}',
  created_at    timestamptz NOT NULL DEFAULT now(),
  last_used_at  timestamptz,
  expires_at    timestamptz,
  revoked_at    timestamptz
);

Note what is missing: there is no column holding the secret. If the generated migration includes a key or token column with the raw value "for convenience," remove it. If the model suggests encrypting the key so it can be shown again later, push back. Being able to display a key again means being able to leak it again.

Verify keys with a lookup plus a constant-time comparison

Verification should be two steps: parse the key, find the row by its public key_id, then compare the hash of the presented secret to the stored hash with a constant-time function. Comparing with == can, in principle, leak how many leading characters matched through response timing. Python provides hmac.compare_digest for exactly this.

from datetime import datetime, timezone

def verify_api_key(presented: str, db, pepper: bytes):
    parts = presented.split("_")
    if len(parts) != 4 or parts[0] != "tn" or parts[1] not in ("live", "test"):
        return None
    _, mode, key_id, secret = parts
    row = db.fetch_one(
        "SELECT * FROM api_keys WHERE key_id = %s AND mode = %s", (key_id, mode)
    )
    if row is None:
        return None
    if not hmac.compare_digest(row["secret_hash"], hash_secret(secret, pepper)):
        return None
    now = datetime.now(timezone.utc)
    if row["revoked_at"] is not None:
        return None
    if row["expires_at"] is not None and row["expires_at"] <= now:
        return None
    return row

Two things to check in generated verification code. First, every failure path should return the same generic 401 response. Do not tell the caller "key exists but is revoked" versus "key not found"; that difference helps someone probing for valid key IDs. Log the specific reason on your side instead. Second, make sure the key arrives in a header, typically Authorization: Bearer ... or a custom header like X-API-Key. Keys in query strings end up in server logs, proxy logs, and browser history.

Enforce scopes in one place

Once a request is authenticated, the key's scopes should limit what it can do. The mistake to look for is scope checks scattered across individual handlers, where one forgotten check turns a read-only key into a full-access key. Ask the model for a single decorator or dependency that declares the required scope per route, and have it deny by default when a route declares nothing.

def require_scope(scope: str):
    def decorator(handler):
        def wrapper(request, *args, **kwargs):
            key = request.api_key
            if key is None or scope not in key["scopes"]:
                return json_error(403, "insufficient_scope")
            return handler(request, *args, **kwargs)
        return wrapper
    return decorator

@require_scope("orders:read")
def list_orders(request): ...

Remember that scopes do not replace ownership checks. A key with orders:read for organization 12 must still only see organization 12's orders. Every query should filter by the key's org_id.

A magnetic stripe hotel key card

Hotel key cards are issued, scoped to one room, and invalidated at checkout. API keys deserve the same lifecycle. Image: Magnetic stripe card - hotel key card by Jackie, CC BY-SA 3.0, via Wikimedia Commons.

Design rotation so customers never need downtime

Keys leak. Someone pastes one into a support ticket, commits a .env file, or leaves a company. Rotation needs to be routine, which means it has to be safe. The pattern that works:

  1. The customer creates a second key while the first one keeps working.
  2. They deploy the new key to their systems.
  3. They watch the old key's last_used_at stop advancing.
  4. They revoke the old key.

This only works if your system allows multiple active keys per owner and shows when each was last used. Updating last_used_at on every request can add a write to every API call, so ask for it to be throttled, for example updating only when the stored value is more than a few minutes old.

For emergencies, also give yourself an internal way to revoke a key immediately, and make sure revocation takes effect right away. If you add a cache in front of key lookups to save database reads, keep the cache lifetime short and clear the entry on revoke, or a revoked key will keep working until the cache expires.

Log usage, never the key

Log the key_id, organization, route, and response status for every authenticated request. That gives you an audit trail and lets you answer "which integration made this call?" What should never appear in logs is the full key or the secret part. Generated logging code often dumps all request headers for debugging. Check that the Authorization and X-API-Key headers are redacted, including in error reports sent to third-party monitoring services.

A prompt that gets most of this right the first time

I am adding API key authentication to a Python Flask API backed by PostgreSQL.
Existing tables: organizations(id, name), users(id, org_id, email).

Requirements:
- Keys belong to an organization; record the creating user.
- Multiple active keys per org; each has a name, scopes (text array),
  mode (live/test), optional expires_at, revoked_at, last_used_at.
- Key format: tn_{mode}_{key_id}_{secret}, using the secrets module,
  secret = 32 random bytes.
- Store only HMAC-SHA-256(secret) with a pepper read from an env var.
  No column may contain the raw key. Return the full key only once on creation.
- Verify by looking up key_id, then hmac.compare_digest on the hash.
  All failures return the same 401 body. Log the real reason server-side.
- Accept the key only from the Authorization: Bearer header.
- A require_scope decorator; routes without a declared scope are denied.
- Throttle last_used_at updates to once per 5 minutes per key.
- Redact Authorization headers in all logging.

Give me: the migration, the key module, the middleware, the decorator,
create/list/revoke endpoints, and pytest tests for each failure case.

Tests to insist on

Do not accept the code until tests cover the cases that matter:

  • A valid key authenticates and returns the right organization.
  • A key with a correct ID but a wrong secret is rejected.
  • Revoked and expired keys are rejected, with the same 401 body as an unknown key.
  • A test-mode key cannot authenticate against live mode.
  • A key without the required scope gets a 403.
  • A key for one organization cannot read another organization's records.
  • A key in the query string is not accepted.
  • The database never contains the raw key after creation (query the table in the test and assert the secret does not appear).
  • Logs captured during a request do not contain the secret.

That last pair is easy to forget and catches the regressions that matter most, such as a later change that adds a debugging column or a verbose log line.

A short review checklist

  • Keys come from a secure random source with enough length and a distinctive prefix.
  • Only a keyed hash is stored; the full key is shown once.
  • Lookup by public ID, comparison in constant time.
  • Generic 401 responses, detailed reasons in server logs only.
  • Keys accepted from headers only.
  • Scopes enforced centrally, deny by default, plus ownership filtering on every query.
  • Multiple keys per owner, visible last-used times, instant revocation.
  • No keys in logs or error reports.

An LLM can write all of this in a few minutes. The value you add is deciding what a key means in your system, stating the security requirements up front, and refusing code that quietly stores the secret or skips the tests. Do that, and API keys become a feature customers trust instead of the credential that shows up in your next incident report.

Comments

Popular posts from this blog

Grok Bot - a step closer to AGI

Tencent Hy4 Preview: Open 770B MoE Built for Real Work

Structured Outputs and Constrained Decoding for Reliable LLM APIs in Production (September 2026)