An API key starts as a row with a random string. Then a customer asks whether they can scope one to a single environment, what happens when the engineer who created it leaves, whether they can rotate it without downtime, and how they would know if it leaked. Those four questions are the actual feature.
The good news is that all four have well-understood answers, and they cost far less if you build them before the keys exist than after.
Store a hash, show the value once
A key is a credential, so it lives in your database the way a password does: hashed, never recoverable, displayed exactly once at creation with a clear warning. A product that can show you an existing key can also leak every key it holds in a single query, and there is no good reason to accept that risk to save a customer one regeneration.
Give the key a visible prefix that identifies your product and its environment, and store a short fingerprint alongside the hash. The prefix lets secret scanners recognise it in a public repository and tell you; the fingerprint lets your interface and your logs refer to a specific key without holding the key itself.
- Hash with a slow algorithm and verify on use; the request is not that hot
- Prefix by product and environment so a leaked key is identifiable on sight
- Show once, store a fingerprint, never offer a reveal button
- Record last-used time and address, coarsely, so unused keys can be found
A product that can show you an existing key can leak every key it holds in one query.
Rotation needs two live keys
You cannot rotate a single-slot credential without downtime. The customer must be able to create the replacement, deploy it, confirm traffic has moved, and only then revoke the old one. That means multiple active keys per account, each independently revocable, and a way to see which of them is still receiving requests.
Last-used timestamps make the whole flow safe. An administrator staring at a key with no traffic for a fortnight will revoke it confidently; without that signal, the same person leaves it in place forever because nobody wants to be the one who broke a production integration on a Friday.
Ownership, scope and the leaver problem
A key created by a person and carrying that person's permissions becomes a problem the day they leave. If you deactivate them and their keys keep working, access outlives the account; if you revoke the keys, an integration nobody knew about stops. Both outcomes come from the same mistake, which is letting a machine credential inherit a human's authority.
Bind keys to the organisation with an explicit scope of their own, and record who created one purely as history. Then offboarding is a question about people, key rotation is a question about services, and the two stop being entangled. Every issue, use of a new key, scope change and revocation belongs in the audit trail, because this is precisely the area a reviewer will ask about.
- Key belongs to the organisation; the creator is metadata, not the authority
- Scope down to what the integration calls, not to what its author could do
- Expiry as an option, with a warning before it lands
- Revocation takes effect immediately, including for requests already in flight
Everything here, already built
Sign-in, enterprise SSO, directory provisioning, roles and an audit trail behind one API. Start with the quickstart and have a working sign-in this afternoon.