HashiCorp Vault Token Management: Complete Authentication

In HashiCorp Vault, a token is the credential every request carries, and you manage its whole life with four commands: vault token create mints one (with a policy, a TTL, and a type), vault token lookup inspects it, vault token renew extends its TTL up to a hard max_ttl ceiling, and vault token revoke kills it and — by default — every child token it spawned. The single most important decision is picking the right token type: service tokens are the renewable default stored in Vault, batch tokens are lightweight encrypted blobs for high-volume CI/CD that cannot be renewed or individually revoked, periodic tokens renew forever as long as you renew inside the period window, and root tokens bypass all policy and should be revoked the moment you finish an emergency task.

That is roughly the summary an AI overview would give you. What it can't show you is why a token you renewed still died at hour 24, the exact CLI flag that lets an operator revoke a token they can't see, or which type to reach for when a background worker must outlive the human who created it. The lifecycle diagram, the type-selection table, and the symptom-to-fix table below answer those — the parts that actually break in production.

Token Types at a Glance: Which One Should I Use?

Before touching a single flag, decide the type. It changes whether the token can be renewed, whether it survives its parent, and whether it even lives in Vault's storage at all.

Rule of thumb: default to service tokens for interactivity, switch to batch only when performance metrics prove the token store is the bottleneck, use periodic (usually -orphan) for daemons, and treat root as a fire alarm — break the glass, use it, revoke it.

The Token Lifecycle: TTL vs. Max TTL

The number-one confusion in Vault token management is a renewable token that suddenly stops renewing. The cause is almost always the max_ttl ceiling. TTL is the current countdown; renewal resets it — but never past the absolute max_ttl wall set when the token was born.

Renewal resets TTL — but never past max_ttl

# Set environment variable for convenience
export VAULT_ADDR='http://127.0.0.1:8200'

# Authenticate with a token
vault login <your-token>

# Create a basic service token
vault token create

# Create with specific TTL and policies
vault token create -ttl=4h -policy=readonly

# Create a batch token
vault token create -type=batch -ttl=1h -policy=readonly

# Create a periodic token with 24-hour period
vault token create -period=24h -policy=app-policy

# Create an orphan token
vault token create -orphan -ttl=8h -policy=service-policy

# Root tokens are typically created during initialization
# or regenerated using unseal keys
vault operator generate-root -init

# Create a token with default settings
vault token create

# Output includes:
# - token (the secret value)
# - token_accessor (for management)
# - token_duration (TTL)
# - token_policies (attached policies)

# Create token with specific TTL
vault token create -ttl=2h

# Create token with policies
vault token create -policy=readonly -policy=database-access

# Create renewable token with max TTL
vault token create -ttl=1h -explicit-max-ttl=24h -renewable=true

# Create token with display name (for audit logs)
vault token create -display-name="jenkins-ci"

# Create token with metadata
vault token create -metadata=environment=production -metadata=team=platform

# Create token limited to specific uses
vault token create -use-limit=5  # Token becomes invalid after 5 uses

Creating Tokens for Applications

For applications, create tokens with appropriate constraints:

# Web application token: renewable, reasonable TTL
vault token create \
  -policy=web-app \
  -ttl=1h \
  -explicit-max-ttl=24h \
  -renewable=true \
  -display-name="web-app-prod"

# Batch job token: short-lived, non-renewable
vault token create \
  -type=batch \
  -policy=batch-job \
  -ttl=30m

# Long-running service: periodic token
vault token create \
  -policy=background-service \
  -period=12h \
  -orphan \
  -display-name="background-worker"

Token Lifecycle Management

Understanding and managing token lifecycles is critical for security.

TTL and Max TTL

• TTL (Time To Live): Initial lifespan of the token
• Max TTL: Maximum possible lifetime, even with renewals

# Create token with 1-hour TTL and 24-hour max TTL
vault token create -ttl=1h -explicit-max-ttl=24h

# This token can be renewed hourly up to 24 times total

Token Renewal

Renew tokens before they expire to maintain access:

# Renew current token
vault token renew

# Renew with specific increment
vault token renew -increment=2h

# Renew a specific token
vault token renew <token>

# Renew by accessor (when you don't have the token value)
vault token renew -accessor <accessor>

Important: Renewal cannot extend a token beyond its max TTL. Plan your token strategy accordingly.

Checking Token Status

# Look up current token
vault token lookup

# Look up specific token
vault token lookup <token>

# Look up by accessor
vault token lookup -accessor <accessor>

Example output:

Key                  Value
---                  -----
accessor             abc123def456
creation_time        1704067200
creation_ttl         1h
display_name         token-jenkins
entity_id            n/a
expire_time          2024-01-01T13:00:00Z
explicit_max_ttl     24h
id                   hvs.CAESIJK...
issue_time           2024-01-01T12:00:00Z
meta                 map[environment:prod]
num_uses             0
orphan               false
path                 auth/token/create
policies             [default jenkins-policy]
renewable            true
ttl                  45m30s
type                 service

Token Accessors

Accessors allow token management without exposing the actual token value.

Using Accessors

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

# Look up token by accessor
vault token lookup -accessor <accessor>

# Renew by accessor
vault token renew -accessor <accessor>

# Revoke by accessor
vault token revoke -accessor <accessor>

Why Use Accessors?

1. Security: Operators can manage tokens without seeing their values
2. Audit: Track token usage without logging sensitive values
3. Automation: Scripts can manage tokens safely
4. Delegation: Grant token management without full token access

Token Revocation

Properly revoking tokens is essential for security hygiene.

Revocation Methods

# Revoke specific token
vault token revoke <token>

# Revoke current token
vault token revoke -self

# Revoke by accessor
vault token revoke -accessor <accessor>

# Revoke token and all its children (default behavior)
vault token revoke <token>

# Revoke token but orphan its children
vault token revoke -mode=orphan <token>

Bulk Revocation

# Revoke all tokens from a specific auth method
vault token revoke -mode=path auth/userpass/login/admin

# Revoke tokens by prefix (requires specific accessor patterns)
vault list auth/token/accessors | xargs -I {} vault token revoke -accessor {}

Token Revocation Best Practices

1. Revoke promptly: Revoke tokens as soon as they're no longer needed
2. Use short TTLs: Prefer short-lived tokens that expire automatically
3. Monitor accessors: Track active tokens and revoke suspicious ones
4. Revoke on incidents: Revoke potentially compromised tokens immediately

Token Policies

Policies determine what operations a token can perform.

Attaching Policies

# Create token with multiple policies
vault token create -policy=readonly -policy=secrets-reader -policy=database-creds

# The token inherits permissions from all attached policies

Policy Inheritance

Tokens inherit policies from:

1. Explicitly attached policies (-policy flag)
2. Identity entity policies (if using identity secrets engine)
3. Default policy (unless -no-default-policy specified)

# Create token without default policy
vault token create -no-default-policy -policy=minimal-access

Viewing Token Policies

# Check policies on current token
vault token lookup | grep policies

# Check specific token's policies
vault token lookup <token> | grep policies

Token Roles

Token roles define templates for creating tokens with consistent settings.

Creating Token Roles

# Create a role for CI/CD tokens
vault write auth/token/roles/ci-runner \
  allowed_policies="ci-policy,readonly" \
  disallowed_policies="admin" \
  orphan=true \
  renewable=true \
  token_period=1h \
  token_explicit_max_ttl=12h

Using Token Roles

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

# The token inherits all settings from the role

Role Benefits

1. Consistency: All tokens from a role have identical settings
2. Governance: Control what policies can be attached
3. Simplicity: Operators don't need to remember complex flags
4. Audit: Easily track tokens created from specific roles

Best Practices

1. Use Short TTLs

# Prefer short-lived tokens
vault token create -ttl=1h -explicit-max-ttl=8h

# NOT this:
vault token create -ttl=30d  # Too long!

2. Apply Least Privilege

# Create purpose-specific policies
vault policy write db-readonly - <<EOF
path "database/creds/readonly" {
  capabilities = ["read"]
}
EOF

# Attach only necessary policies
vault token create -policy=db-readonly

3. Use Token Roles for Standardization

# Define roles for different use cases
vault write auth/token/roles/webapp allowed_policies="webapp-policy" token_ttl=1h
vault write auth/token/roles/batch allowed_policies="batch-policy" token_type=batch token_ttl=30m

4. Prefer Auth Methods Over Direct Token Creation

# Better: Use AppRole for applications
vault write auth/approle/role/myapp policies="app-policy"

# Instead of: Creating tokens manually for apps

5. Monitor and Audit

# Enable audit logging
vault audit enable file file_path=/var/log/vault_audit.log

# Regularly review token accessors
vault list auth/token/accessors

6. Never Store Root Tokens

Root tokens should be:

• Generated only when needed
• Used immediately for the specific task
• Revoked immediately after use
• Never stored in configuration files or scripts

Troubleshooting Common Issues

Most Vault token failures produce the same generic permission denied message regardless of root cause. This table maps the real symptom to the actual cause and the one command that fixes it — the diagnostic path an error string alone won't give you.

Token Expired

Error: permission denied or token expired

Solution:

# Check token status
vault token lookup

# If expired, reauthenticate
vault login

Cannot Renew Token

Error: token is not renewable

Causes:

• Token created with -renewable=false
• Batch tokens (not renewable by design)
• Token already at max TTL

Solution: Create a new token with appropriate settings

Policy Denied

Error: permission denied on specific path

Solution:

# Check token policies
vault token lookup | grep policies

# Verify policy grants needed capabilities
vault policy read <policy-name>

Orphan Token Confusion

Issue: Child tokens still exist after revoking parent

Explanation: If parent was revoked with -mode=orphan, children remain active.

Solution:

# Revoke without orphaning (default)
vault token revoke <parent-token>
# This revokes all children too

Token Use Limit Reached

Error: token has already been used

Cause: Token created with -use-limit has exhausted its uses

Solution: Create a new token or use one without use limits

Command Reference

Conclusion

Effective token management is fundamental to Vault security. By understanding token types, implementing proper lifecycle management, and following best practices, you can maintain a secure and efficient secrets management infrastructure.

Key takeaways:

• Choose the right token type for each use case
• Use short TTLs and renew as needed
• Apply least privilege with specific policies
• Use token roles for consistency
• Monitor and audit token usage regularly
• Revoke promptly when tokens are no longer needed

For more advanced Vault topics, see our guides on installing HashiCorp Vault and root token regeneration.