A support ticket that reads "our API key stopped working after the user changed their password" reveals a design mistake before the ticket is even fully read: an API key and a user's authentication credential were treated as interchangeable, when they answer different questions for different kinds of caller. An API key identifies a client — this request is coming from Acme Corp's integration, or from our own mobile app's build — while a token typically represents a subject with specific, time-bounded permissions, often derived from a real user's authenticated session. Confusing the two produces exactly the kind of coupling that ticket describes, and worse, produces the security gaps this lesson exists to prevent: a long-lived key doing a token's job with none of a token's expiry discipline, or a per-user token doing a key's job with no way to scope it to just the integration that actually needs it.
This lesson draws the distinction cleanly and then covers the operational discipline each credential type actually needs — scoping, rotation, and storage — because the distinction alone does not prevent an incident if a correctly-classified API key still sits unrotated in a public repository for two years.
Nothing here requires a specific vendor's implementation. The concepts — client identity versus subject identity, and the lifecycle discipline each demands — apply whether the mechanism is a raw string compared against a database, or a cryptographically signed structure like a JWT.
Analogy🏏Cricket
🏏 Think of it like cricket: A stadium issues two structurally different kinds of credential for two structurally different kinds of question. A broadcaster's equipment pass identifies which broadcasting company is authorized to bring cameras into the ground at all — it answers "which organization is this," is typically valid for an entire season or tournament, and is not tied to any specific individual technician. A specific technician working for that broadcaster also carries a personal, dated accreditation badge that answers a completely different question — "which specific person is this, and is their access current today" — issued fresh, checked at each door, and revoked the moment that individual's employment or assignment ends. A ground that let the broadcaster's season-long equipment pass double as an individual technician's daily identity badge would have no way to revoke access for one specific person who left the company without also cutting off the entire broadcaster's equipment access — exactly the coupling failure this lesson opens with. Just as an equipment pass answers "which organization" while a personal badge answers "which specific person, right now," an API key answers "which client integration" while a token typically answers "which specific subject, with what permissions, until when." Just as conflating the two credential types at a stadium removes the ability to revoke one without breaking the other, conflating an API key with a per-user token removes the ability to rotate or revoke one without disrupting a system that was never actually built to be coupled to it. The insight is that a credential's design should match the specific question it needs to answer, because a credential doing double duty for two different questions can only be revoked, rotated, or scoped as coarsely as its most demanding use requires.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.