HashiCorp Vault Token Management: Complete Authentication Guide

📚 Part of the HashiCorp Vault: The Complete Guide to Secrets Management series.

title: "HashiCorp Vault Token Management: Complete Authentication" date: "2025-10-15" lastUpdated: "2026-01-15" excerpt: "Master Vault token management: create, renew, revoke tokens using CLI. Learn token types, policies, TTLs, and security best practices for HashiCorp Vault authentication." author: "InventiveHQ Team" category: "Secrets Management" tags:

• hashicorp
• vault
• secrets management
• authentication
• tokens heroImage: "https://imagedelivery.net/GtU8Bnoa3QuAEdxQ_M9RPA/af30d61a-3faa-4b19-2b7d-26d0cc1fb600/public" relatedPosts:
• hashicorp-vault-cli-install-and-gui-setup-guide
• vault-root-token-regeneration-complete-guide-inventivehq faqItems:
• question: "What are the different types of Vault tokens?" answer: "Vault has several token types: root tokens (unlimited access), service tokens (standard tokens with TTL), batch tokens (lightweight, non-renewable), periodic tokens (renewable indefinitely within period), and orphan tokens (no parent relationship). Each serves different use cases."
• question: "How do I create a new Vault token?" answer: "Create a token with 'vault token create'. Add options like '-policy=my-policy' to attach policies, '-ttl=1h' for time-to-live, '-renewable=true' for renewal capability, or '-orphan' to create without parent relationship."
• question: "How do I renew a Vault token before it expires?" answer: "Renew your current token with 'vault token renew' or a specific token with 'vault token renew '. You can also specify increment: 'vault token renew -increment=1h'. Renewal extends the TTL up to the max_ttl limit."
• question: "How do I revoke a Vault token?" answer: "Revoke a token with 'vault token revoke ' or by accessor with 'vault token revoke -accessor '. Use '-self' to revoke your current token. Add '-mode=orphan' to leave child tokens active."
• question: "What is a token accessor and when should I use it?" answer: "A token accessor is a reference to a token that allows limited operations (lookup, renew, revoke) without exposing the actual token value. Use accessors when you need to manage tokens but shouldn't have access to their secret values."
• question: "What is the difference between TTL and max TTL?" answer: "TTL (time-to-live) is the initial lifespan of a token. Max TTL is the absolute maximum lifetime—a token cannot be renewed beyond this limit. For example, a token with 1h TTL and 24h max_ttl can be renewed up to 24 times."
• question: "What are orphan tokens in Vault?" answer: "Orphan tokens have no parent token, so they aren't automatically revoked when their creator's token expires. Create orphan tokens with 'vault token create -orphan'. Use them for long-running services that shouldn't depend on the creating token's lifecycle."
• question: "How do I look up token information?" answer: "Look up your current token with 'vault token lookup'. Look up another token with 'vault token lookup ' or by accessor with 'vault token lookup -accessor '. This shows policies, TTL, creation time, and other metadata."
• question: "What are periodic tokens and when should I use them?" answer: "Periodic tokens can be renewed indefinitely as long as renewal happens within the period interval. Create with 'vault token create -period=24h'. Use for long-running applications that need persistent access without token recreation."
• question: "How do I attach policies to a Vault token?" answer: "Attach policies when creating a token with 'vault token create -policy=policy1 -policy=policy2'. The token inherits permissions from all attached policies. You cannot add policies to an existing token—create a new one instead."

Understanding token management is crucial for maintaining secure, scalable Vault deployments. This comprehensive guide covers token authentication, creation strategies, lifecycle management, and security best practices using the Vault CLI.

Token Authentication Fundamentals

Tokens are the primary authentication method in HashiCorp Vault. Every interaction with Vault requires a valid token, which determines what operations are permitted based on attached policies.

How Token Authentication Works

When you authenticate to Vault—whether using the root token, userpass, LDAP, or any other method—Vault issues a token. This token is then used for all subsequent requests:

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

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

After successful authentication, the token is stored locally (typically in ~/.vault-token) and automatically used for future commands.

Token Structure

Every Vault token contains:

• Token ID: The secret value used for authentication
• Accessor: A reference ID for managing the token without exposing its value
• Policies: Permissions attached to the token
• TTL/Max TTL: Lifespan configuration
• Metadata: Optional key-value data

Understanding Token Types

Vault supports several token types, each designed for specific use cases.

Service Tokens (Default)

Service tokens are the standard token type with full functionality:

# Create a basic service token
vault token create

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

Characteristics:

• Stored in Vault's token store
• Support renewal (if configured)
• Can have child tokens
• Counted against performance quotas

Batch Tokens

Batch tokens are lightweight, encrypted tokens ideal for high-volume scenarios:

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

Characteristics:

• Not stored in Vault's token store
• Cannot be renewed or revoked individually
• Cannot have child tokens
• Lower overhead, better performance
• Encrypted blob containing all token information

Best for: High-frequency, short-lived operations like CI/CD pipelines

Periodic Tokens

Periodic tokens can be renewed indefinitely, as long as renewal happens within the period:

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

Characteristics:

• No maximum TTL constraint
• Must be renewed within the period to remain valid
• Useful for long-running services

Best for: Services that need persistent access without predetermined end dates

Orphan Tokens

Orphan tokens have no parent, so they're not revoked when their creator's token expires:

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

Characteristics:

• Independent lifecycle
• Not affected by parent token revocation
• Must be explicitly revoked

Best for: Services that should outlive the human operator who created the token

Root Tokens

Root tokens have unlimited privileges and bypass all policy checks:

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

Characteristics:

• Unlimited access to all Vault operations
• No expiration by default
• Should be revoked immediately after use

Best for: Emergency recovery only—never for routine operations

Creating Tokens

The vault token create command offers extensive options for customizing token behavior.

Basic Token Creation

# 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)

Token Creation Options

# 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

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.