Scope API Tokens So a Leak Cannot Touch Everything

A token will leak. Not might, will. Someone commits a key to a public repo, a CI log captures it, a developer pastes it into a chat, a contractor's laptop gets stolen, a dependency gets compromised and exfiltrates the environment. The question is never whether a credential escapes. It is what an attacker can do with it once it does, and that is a question you answer months in advance, when you decide how much power to put behind the token.

The difference between a leaked token that triggers a password rotation and a leaked token that becomes a full breach is the scope you gave it. A token that can read one resource and nothing else is a contained incident. A token that can read, write, and delete everything is a catastrophe. The same principle that stops you from shipping API keys in your frontend bundle applies once a key is out: limit what it can reach. The work below is about making sure that when, not if, a key gets out, it lands in the first category.

Least privilege is the whole game

The principle is old and it is correct: grant a token exactly the permissions the task requires, and nothing more. The standard framing is to think per workflow. A document-summarization service needs read access to the document store. It does not need write, it does not need delete, and it certainly does not need access to the neighboring billing service. So its token gets read on documents and nothing else.

The default posture should be read-only. Write, delete, and admin capabilities are escalations you add deliberately because a specific task genuinely requires them, not defaults you grant because it was easier than thinking about it. Every permission you attach to a token is a permission an attacker inherits if the token leaks. The smallest set that does the job is the only correct set.

Scope by resource and by action, not as one big key

The lazy implementation is a single API key that does everything. It is easy to issue, easy to use, and a disaster when it leaks, because its blast radius is your entire system. The disciplined implementation scopes tokens along two axes: which resources they touch, and which actions they can take on those resources.

Concretely, a scoped token system lets you mint a credential that says "read on projects, write on comments, nothing on users, nothing on billing." Each scope is a resource paired with an action, carried as a claim in the token the same way JWTs attackers cannot forge or replay bind audience and issuer. The token carries only the pairs it needs. Now if that token leaks, the attacker can read projects and write comments. They cannot touch your users, cannot delete anything, cannot reach billing. The incident is bounded by the scopes you chose, and you chose them small.

This is exactly the model we built into a content management system we ship, where API tokens are scoped resource by resource and action by action, so an integration that only needs to publish posts gets a token that can do precisely that and is powerless everywhere else. The same discipline belongs in every system that issues credentials to clients, integrations, or services, and it is non-negotiable when you ship an MCP server that survives real agent traffic, where the agent holding the token is the least predictable consumer you will ever have.

For least privilege to actually hold, the enforcement has to happen at every layer. It is not enough to label a token with a scope. The gateway has to validate the scope on the way in, and the backend has to authorize the specific action against the specific resource on the way through. Scope labels that nobody checks are theater. The check at the point of action is what makes the scope real.

One token per consumer, never one to rule them all

A single shared token across many integrations is a blast-radius multiplier. Compromise that one credential and you have exposed every service it was wired into, including services that had no relationship to wherever the leak actually happened.

The fix is compartmentalization: issue a unique token per tool, per integration, per project. When the analytics integration's token leaks, only the analytics integration's access is exposed. The CRM, the email service, the deploy pipeline, all of them are on separate tokens and all of them are untouched. This is the same instinct as why one leaked secret should never compromise the rest: if one escapes, the others are still safe. A breach in one corner does not become a breach everywhere.

Rotation shrinks the window

Even a perfectly scoped token is dangerous for as long as it remains valid. Rotation is what shrinks that danger over time. By giving tokens a finite lifetime and replacing them on a schedule, you bound how long a stolen credential keeps working. A token that expires in an hour is useful to an attacker for an hour. A token that never expires is useful forever, which is why the one a developer committed to GitHub two years ago is still a live threat today.

Short-lived access tokens are the goal for anything machine-to-machine. For service-to-service traffic specifically, mutual TLS that rotates itself gives each service an identity that expires on its own, which is least privilege applied to the transport. Use refresh tokens only where you genuinely need long-running sessions, and rotate the refresh tokens too. Doing this without an outage is its own skill, the subject of rotating production secrets without taking the app down. Rotation is not a substitute for scoping or revocation; it is the third leg of the same stool, reducing the usable window of any credential that escapes. The combination is what contains incidents: scoping limits what a leaked token can do, rotation limits how long it can do it.

Revocation is your incident response

When you detect a leak, the clock is running, and your ability to respond is only as good as your ability to kill the token. This means two things have to exist before the incident:

• A way to revoke a single token immediately, without disrupting every other token in the system. If revoking the leaked credential means rotating everything and breaking every integration, you will hesitate, and hesitation during a breach is expensive. This is part of what a small team needs before its first security incident.
• A revocation playbook you have actually rehearsed. When token reuse or a leak is detected, the response should be reflexive: revoke the affected token (or the whole token family if you suspect the refresh chain is compromised), force re-authentication, and rotate. Knowing exactly which button to press and what breaks when you press it is the difference between a five-minute containment and an hour of paralysis.

Track ownership while you are at it. Every token should have a known owner, a known purpose, and a known lifetime, so that when something looks wrong you can answer "what is this token, who issued it, and what can it touch" without an investigation.

The four pieces, working together

Secure token management is not one technique. It is four, and they only work as a set:

1. Scoped permissions so a leaked token can touch only a narrow slice of the system.
2. Compartmentalization so each consumer has its own token and a leak does not cascade.
3. Rotation so any credential's usable lifetime is bounded.
4. Revocation and audit so you can kill a token fast and prove afterward what it did.

Drop any one of them and the others weaken. Scoping without revocation means you cannot contain a known leak. Rotation without scoping means a leaked token is still all-powerful for its lifetime. Audit without compartmentalization means you cannot even tell which integration was breached.

We bake all four into every system we build, because the alternative is the all-powerful key that turns a routine credential leak into a company-ending incident. It is the kind of design gap our security audits look for, and the kind of foundation we put under every web app that issues credentials. A token that leaks should cost you a rotation and a shrug, not your business. That outcome is decided long before the leak, by how small you were willing to make the key.