How Use-Limit Tokens Work
A Use-Limit Token behaves like a standard token—honoring both itsttl and max_ttl—but also tracks how many times it can be used. Vault will revoke the token when either of these conditions is met first:
- The token’s time-to-live (TTL) elapses
- The token’s allowed use count reaches zero
Revoking on use limits protects against token replay and limits the blast radius if a token is exposed.
Example Timeline
Imagine you create a token with:- TTL: 24 hours
- Use limit: 3
| Time Elapsed | TTL Remaining | Uses Remaining | Status |
|---|---|---|---|
| 0 hours | 24 hours | 3 | Active |
| 3 hours | 21 hours | 2 | Active |
| 10 hours | 14 hours | 1 | Active |
| 11 hours | 13 hours | 0 | Revoked |
| 24 hours | 0 hours | – | Revoked |
- At ~11 hours, after the third use, the token is revoked immediately—even though it still had TTL left.
- If you waited the full 24 hours but used the token only once, Vault would revoke it on TTL expiry despite remaining uses.
Creating a Service Token with Use Limits
Use the-use-limit flag when generating a token:
- Policy:
training - TTL: 24 hours
- Maximum Uses: 3
Inspecting the Token
To check the remaining uses and TTL, run:num_uses field shows how many times this token can still be used before Vault revokes it.
Simulating Token Usage
Each time the token is used for an operation—such as reading a secret—Vault decrements thenum_uses count. After the final allowed use, the token is revoked immediately.
num_uses reaches 0.
Summary
By defining both a TTL and a-use-limit, Vault tokens can expire on whichever limit is reached first—time or uses. This adds a robust safeguard against token misuse, replay attacks, and unintended long-lived credentials.