API keys should be verifiable, not recoverable

What the public implementation shows

GovPayments generates 32 random bytes for authority API keys, encodes them with a p2g prefix, stores SHA-256 digests, and verifies candidates with a fixed-time comparison.

The hasher separates credential issuance and verification from authority endpoint authorization and database storage. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA gateway rarely needs to recover an API key after issuance; it only needs to verify the presented secret.

The decision behind the mechanism

The plaintext secret exists for issuance while durable state contains a one-way representation sufficient for exact high-entropy key verification.

Storing recoverable API keys turns a database read into immediate partner access; ordinary string comparison can also expose timing differences. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Generate keys from a cryptographic random source.
• Store only the digest and non-secret key metadata.
• Use fixed-time digest comparison.
• Design explicit issuance, rotation, and revocation workflows.

How the control should be operated

Show the key once, support overlapping rotation windows, identify keys without logging secrets, and revoke by disabling or replacing the stored digest.

A database compromise does not directly disclose active integration credentials, and verification behavior remains predictable. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.