HashiCorp Vault — Token Auth

3 minute read

Tokens are Vault’s fundamental authentication unit. Every request to Vault must include a token, and every auth method ultimately produces one. Understanding tokens deeply is essential for operating Vault securely.

Token Types

Vault has two token types:

Feature Service Token Batch Token
Prefix hvs. hvb.
Stored in Vault ✅ Yes ❌ No (self-contained)
Renewable ✅ Yes ❌ No
Can create child tokens ✅ Yes ❌ No
Performance Standard Higher (no storage lookup)
Revocation Immediate Cannot be revoked individually
Best for Interactive use, long-lived High-throughput, batch operations

The Root Token

The root token is created during vault operator init. It has unlimited capabilities:

# Login with root token
vault login hvs.roottoken123

# Root token has the "root" policy
vault token lookup
# policies: ["root"]

⚠️ Best practice: Revoke the root token after initial setup. Generate a new one only when needed.

# Revoke root token
vault token revoke hvs.roottoken123

# Generate a new root token (requires unseal keys)
vault operator generate-root -init
vault operator generate-root -otp="<otp>"
# Provide unseal keys to generate a new root token

Create Tokens

# Create a token with a policy
vault token create -policy=dev-team -ttl=8h

Expected output:

Key                  Value
---                  -----
token                hvs.CAESI...
token_accessor       abc123
token_duration       8h
token_renewable      true
token_policies       ["default" "dev-team"]
identity_policies    []
policies             ["default" "dev-team"]

Token Creation Options

# Token with metadata
vault token create -policy=app-team \
    -metadata=app="payment-service" \
    -metadata=env="production"

# Periodic token (renewable indefinitely, no max TTL)
vault token create -policy=app-team -period=24h

# Orphan token (no parent — not revoked when parent expires)
vault token create -policy=app-team -orphan -ttl=8h

# Token with limited uses
vault token create -policy=app-team -use-limit=10

# Batch token
vault token create -policy=app-team -type=batch -ttl=1h

Token Hierarchy

By default, tokens form a parent-child tree. When a parent is revoked, all children are revoked too:

Root Token
├── Admin Token (8h TTL)
│   ├── CI Token (1h TTL)
│   └── Deploy Token (30m TTL)
└── Service Token (24h TTL)
    └── Worker Token (1h TTL)

If "Admin Token" is revoked:
  → CI Token is revoked
  → Deploy Token is revoked

Orphan tokens break this hierarchy:

# Create an orphan token
vault token create -orphan -policy=my-policy -ttl=24h

# This token is NOT revoked when its creator's token expires

Token TTL and Renewal

# Check token TTL
vault token lookup
# ttl: 7h45m

# Renew your own token
vault token renew

# Renew with a specific increment
vault token renew -increment=4h

# Renew another token
vault token renew hvs.CAESI...

# Renew via API
curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --request POST \
     --data '{"increment": "4h"}' \
     "$VAULT_ADDR/v1/auth/token/renew-self"

TTL rules:

  • ttl — Initial time-to-live
  • max_ttl — Maximum lifetime (cannot renew past this)
  • period — For periodic tokens, renew indefinitely at this interval
  • A token can be renewed up to its max_ttl, then it must be re-created

Token Accessors

Every token has an accessor — a reference that can look up or revoke the token without knowing the token itself:

# List all token accessors
vault list auth/token/accessors

# Look up a token by accessor
vault token lookup -accessor abc123

# Revoke by accessor (useful for admin operations)
vault token revoke -accessor abc123

Token Lookup

# Look up your current token
vault token lookup

# Look up a specific token
vault token lookup hvs.CAESI...

# API equivalent
curl --header "X-Vault-Token: $VAULT_TOKEN" \
     "$VAULT_ADDR/v1/auth/token/lookup-self" | jq

Token Roles

Token roles define templates for token creation:

# Create a token role
vault write auth/token/roles/ci-runner \
    allowed_policies="ci-read" \
    orphan=true \
    token_period=1h \
    renewable=true \
    token_type=service

# Create a token using the role
vault token create -role=ci-runner

Quick Reference

Command Description
vault token create -policy=p -ttl=1h Create token
vault token create -orphan Create orphan token
vault token create -type=batch Create batch token
vault token create -period=24h Create periodic token
vault token lookup Current token info
vault token renew Renew current token
vault token revoke <token> Revoke a token
vault token revoke -accessor <acc> Revoke by accessor
vault list auth/token/accessors List all accessors

Next: Userpass & LDAP

You may also enjoy