Vault Tokens · Topic 3 of 3
Token TTL and Orphan Tokens
Vault Associate (003): token TTL, max TTL and periodic tokens, how renewal is capped, parent and child revocation, and how orphan tokens escape it.
- 5 min
- Includes a diagram
- A token's TTL runs from creation or the last renewal, and expiry revokes the token and its leases.
- The system max TTL is 32 days by default; the mount and the auth method can change the effective maximum.
- An explicit max TTL is a hard limit on any token that has one, periodic ones included.
What it is
Every token except some root tokens has a time to live (TTL). When the TTL ends, Vault revokes the token and the leases it created. The TTL is counted from creation or from the last renewal, whichever is more recent.
Tokens also form a tree. A token created by another token is its child, and revoking the parent revokes the child. An orphan token has no parent, so it sits outside that rule.
How it works
TTL, max TTL and renewal
A renewable service token can have its TTL extended with vault token renew. Renewal stops working once the token is not renewable, has been revoked, or has reached its maximum TTL.
vault token renew
vault token renew -increment=30m <token>
The -increment value is a request. Without --fail-if-not-fulfilled, Vault caps the duration at what it can grant and the command still succeeds.
What sets the ceiling
For an ordinary token, the maximum is worked out at each renewal from three levels:
| Level | Detail |
|---|---|
| System max TTL | 32 days by default, set in the Vault config file |
| Mount max TTL | Set by tuning the mount; can be longer or shorter than the system value |
| Auth method suggestion | Set per role, group or user; can be shorter but not longer |
An explicit max TTL is a hard cap that ignores all three levels.
vault token create -policy=app-read -ttl=1h -explicit-max-ttl=2h
Say this token is created at 10:00. Renewing it at 10:45 for an hour fits, because 11:45 is before the 12:00 cap. Renewing at 11:30 for an hour would reach 12:30, so Vault grants only 30 minutes.
After 12:00 the token cannot be extended and the client must authenticate again.
Periodic tokens
A periodic token has a period instead of a growing age. Its TTL equals the period at creation and resets to the full period on every renewal, so a token renewed within each period never expires.
vault token create -policy=app-read -period=24h
Creating one with vault token create needs a root token or sudo, while token store roles and auth methods such as AppRole can also issue one. If a period and an explicit max TTL are both set, the token acts as periodic but is revoked at the max TTL. Vault ignores -increment for periodic tokens.
Parents, children and orphans
By default a new token is a child of the token that made it. Revoking a parent revokes all its children and their leases, so nobody can dodge revocation by chaining child tokens.
An orphan has no parent. There are four ways to get one:
- Write access to
auth/token/create-orphan - Sudo or root on
auth/token/createwithno_parentset to true - Token store roles
- Logging in through any auth method other than
token
vault token create -orphan -policy=app-read
vault token revoke -mode=orphan <token>
The first command needs sudo. The second revokes only that token and leaves its children as orphans. An orphan still expires at its own TTL, so only the parent link is missing.
How the exam asks about this
- "A parent token is revoked. What happens to the child tokens?" They are revoked too, unless they are orphans or revoked with
-mode=orphan. - "A service that must stay authenticated indefinitely renews every few hours." Use a periodic token.
- "A token must keep working after the token that created it is revoked." Use an orphan token.
What to remember for the exam
- A token's TTL runs from creation or the last renewal, and expiry revokes the token and its leases.
- The system max TTL is 32 days by default; the mount and the auth method can change the effective maximum.
- An explicit max TTL is a hard limit on any token that has one, periodic ones included.
- A periodic token resets to its period on each renewal, and
vault token create -periodrequires root or sudo. - Revoking a parent revokes its children; orphans are not affected.
- A token with a use limit expires after its last use, even if TTL remains.
Orphan does not mean immortal. An orphan survives its parent's revocation but still expires at its own TTL and max TTL, and vault token create -orphan needs sudo or root.
Common mistakes
Assuming renewal always adds the requested time. The increment is a request. Vault caps it at the ceiling, so near the max TTL a renewal may grant only a few minutes.
Treating every long-lived token as periodic. A normal token is bound by the max TTL calculation, and only a period (or root) removes the expiry. Periodic tokens are meant for long-running services, not people.
Believing a batch token can be extended. Batch tokens have a fixed TTL, no renewal and no explicit max TTL.
Check yourself
When does Vault revoke the leases of a token?
When the token expires or is revoked, Vault also revokes the leases it created. Revoking a parent token does the same for its children and their leases.
How does a periodic token differ from a normal token?
Its TTL resets to the full period at each renewal, so renewing within every period keeps it alive without the usual max TTL ceiling, although an explicit max TTL still applies. Creating one directly needs root or sudo.
Which command revokes a token but keeps its children alive?
vault token revoke -mode=orphan <token>. The children become orphan tokens.
Topic 3 of 3 in Vault Tokens
Test yourself on Vault Tokens
The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.