API keys you can actually rotate

#The one rule

The raw key is returned once, at creation, and never stored. Only a hash of it goes in the database. A dump therefore contains no usable credentials, and there is no endpoint that shows a key again, so there is nothing to socially engineer.

This is not novel and it is worth stating, because the alternative keeps reappearing in codebases whose authors know better. It reappears because a support workflow asked for it, and the correct response to that request is to issue a new key rather than reveal the old one.

#Why rotation does not happen

Almost every system supports rotation and almost none of them rotate. The reason is mechanical. If rotating means updating a secret and redeploying every consumer simultaneously, it is a coordinated change with a window and a rollback plan, so it happens once when an auditor asks and then not again.

Zero trust guidance pushes toward short-lived credentials for exactly this reason [2], and most systems cannot get there in one step.

#The grace window

Rotation creates a new key while the old one stays valid for a defined period. Both validate. The consumer picks up the new one on its own schedule, and the old one expires on a date both sides agreed.

1res, err := eng.RotateKey(ctx, keyID, keysmith.RotateInput{
2    Grace: 14 * 24 * time.Hour, // both keys validate until this elapses
3})
4// res.Raw is the new key, returned exactly once.
Copy

That converts rotation from an event into a background process. It also means an emergency revocation is a distinct operation with grace set to zero, which is the right shape: the routine case is safe and the urgent case is explicit.

#Scoping

A key that can do everything is a key whose compromise is total. Scopes attached at creation, checked on every use, are least privilege applied to machine credentials [1].

The practical difficulty is that scopes are chosen by whoever creates the key, usually at the start of an integration when nobody knows what it will need. The mitigation that helped was recording which scopes a key actually used, so a periodic review can propose narrowing rather than asking somebody to guess.

#Usage recording

Per request, with daily and monthly aggregation. This exists for billing and it earns its place during incidents, because the first question after a suspected leak is what that key has been doing and from where.

Without usage history the answer is nothing, and the only safe response is to revoke everything.

#Where keys are the wrong tool

For a user-facing integration where the user has an account, a delegated authorisation flow is better, because the credential is scoped to what the user permitted and can be withdrawn by them [3]. API keys are for machine-to-machine access where there is no user in the loop, and using them where a user exists means building consent and revocation yourself, badly.