Why it matters
An API key is a credential with an owner, scope and lifecycle. Treat it as a product feature that administrators can inspect and revoke, not as a secret string pasted into a settings page.
An API key gives a machine durable access. Customers need to know who created it, what it can do and how to revoke it without waiting for support.
Decisions to make
- Choose account ownership, permissions and expiration policy.
- Decide whether the key can act across workspaces.
- Show last use without revealing the secret again.
- Choose key scopes, expiration and rotation policy.
- Decide whether keys belong to users, organizations or service accounts.
Build checklist
- Generate high-entropy secrets and store only a verifier.
- Display the secret once, over a protected connection.
- Test revocation and scope checks across every API route.
- Store only a verifier or hash of each secret.
- Show the full key only once and provide safe last-used metadata.
Common mistakes
- Giving machine credentials the full rights of the person who created them.
- Putting a raw API key in logs or analytics.
- Letting a key inherit every permission of the person who created it forever.
Tools & references
3 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
