Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Policies and Tokens

Vault Tokens: Types, TTLs, Hierarchy and Revocation

Learn how Vault tokens work: service vs batch vs periodic tokens, TTL and max TTL, renewal, parent and child tokens, orphans, accessors, use limits and revoking a token tree.

A token is the thing a client presents to Vault, in the X-Vault-Token header or the VAULT_TOKEN variable. Whatever login method you use (see the authentication chapter), the result is a token that carries policies and a lifetime. Understanding token types and how they relate to each other lets you choose short lifetimes, limit damage and clean up automatically.

Vault is not available on this site. Commands are real; the js blocks are labelled stand-ins that model token behaviour.

Token types

Type Stored on disk? Renewable Children Typical use
Service (hvs. prefix) Yes Yes Yes Default; long-running apps
Batch (hvb. prefix) No, encrypted blob No No Huge request volume, performance standbys
Periodic Yes (service) Yes, forever Yes Long-lived daemons, no max TTL
Root Yes n/a Yes Bootstrap only

Service tokens cost storage and replication but offer every feature. Batch tokens are lightweight and cheap but cannot be renewed, have no accessor and cannot create children.

Terminal
vault token create -policy=app-readonly -ttl=30m
vault token create -type=batch -policy=app-readonly -ttl=5m
vault token create -period=24h -policy=agent

TTL, max TTL and renewal

Each token has a TTL, the time until it expires, and a system or mount max TTL that caps total life. Renewing resets the TTL to its full value, but never past the max TTL.

Terminal
vault token lookup
vault token renew
vault token renew -increment=2h

A periodic token has no max TTL: as long as it is renewed within each period, it lives on. That suits a daemon that must run for months, but it deserves tight policies and monitoring.

JS Stand-in: TTL, renewal and max TTL

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Parent and child tokens

A token created by another token becomes its child. This forms a tree, and revoking a token revokes all its children. That is deliberate: if a deployment tool's token is compromised, revoking it also kills every token it issued.

flowchart TD
    P["Parent token (CI)"] --> C1["Child: app A"]
    P --> C2["Child: app B"]
    C1 --> G["Grandchild"]
    O["Orphan token"] -.->|"no parent"| X["Independent tree"]

Revoking the parent removes the whole subtree; an orphan sits outside it.

An orphan token has no parent, so it survives when its creator is revoked. Create one with vault token create -orphan (needs sudo on the create-orphan path or the auth method creates them for you). Tokens from auth methods are orphans by design.

Accessors, use limits and cubbyhole

  • Every service token has an accessor, a non-secret handle. With it you can look up metadata, renew or revoke a token without knowing the token itself: vault token lookup -accessor <accessor>.
  • Use limit (-use-limit=1) makes a token expire after N uses. Combined with response wrapping, it creates one-time delivery of a secret.
  • Each token has a private cubbyhole (cubbyhole/) that only it can read; the contents vanish with the token.
JS Stand-in: revoking a token tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Use short TTLs (minutes to hours) and renew only as needed.
  • Prefer auth methods that issue tokens automatically over hand-made tokens.
  • Revoke by accessor in incident response: vault token revoke -accessor <id>.
  • Revoke the initial root token once you have configured admin access.
  • Use batch tokens for fan-out workloads where no renewal is wanted.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to child tokens when a parent token is revoked?

    Revocation walks the tree and revokes every descendant.
  2. 2. Which token type cannot be renewed and has no accessor?

    Batch tokens are encrypted blobs, not stored, so they cannot be renewed or looked up by accessor.
  3. 3. What is special about a periodic token?

    Periodic tokens can live indefinitely if renewed in time.
  4. 4. What is an accessor used for?

    The accessor is a non-secret reference to a token.

Summary

  • Service tokens are full-featured; batch tokens are lightweight; periodic tokens renew indefinitely.
  • TTL is capped by max TTL; renewal resets TTL.
  • Children die with their parent unless they are orphans.
  • Accessors, use limits and the cubbyhole help you manage tokens safely.

Next: Identity: Entities and Groups