Skip to content

Hashicorp Vault: An Inquiry into the Nature of Tokens

By Sebastian Günther

—

—

Posted in Hashicorp_vault

Hashicorp Vault is a secrets management tool. It provides secure storage for access credentials, certificates, or general encryption/decryption processes. To get access to any secrets, tokens are issued, providing compact, fine-grained and time-based access controls.

Tokens are fundamental to Hashicorp Vault. Operationally, it is a default authentication engine that can not be moved or recreated. Technically, tokens link static secret data or dynamic secrets data at an external application for a specific time. And conceptually, tokens can be short-lived in memory, renewable and persisted on disk, and even form parent-child relationship.

This article explores and explains all aspects of tokens in Hashicorp Vault. It starts with an overview about the authentication method and data structure of tokens, continues with an explanation of token properties, and distinguishes concrete tokens with respect to their type, capabilities, and origin.

The technical context of this article is hashicorp_vault_v.1.20, published 2025-06-25. All provided information and command examples should be valid with newer versions too, baring update to the syntax of CLI commands.

The background material for this article stems from the official Hashicorp Vault documentation about Tokens, Introduction to tokens, and Token authentication method.

Token Auth Method & Data Structure

Hashicorp Vault is implemented as a multi-layer software stack, in which plugins provide flexible, functional extensions. Authentication methods are a plugin type too, and with the vault auth command group, CRUD operations for all authentication methods are provided.

The token auth method is special for several reasons. First, its activated by default at the path auth/token. Second, it can not be moved to another path, or disabled. Third, its unique, no other token auth method can be activated. Therefore, only one subcommand can be used: vault auth tune to change properties like the TTL of issued tokens.

Tokens are compact data structure with essential operational information. Here is an example for a conventional service token.

Key                 Value
---                 -----
accessor            qRxCEersNAAzbMV3Pgc3vEUh
creation_time       1754812487
creation_ttl        1h
display_name        token
entity_id           n/a
expire_time         2025-08-10T10:54:47.738244+02:00
explicit_max_ttl    0s
id                  hvs.CAESIKF8Vk06yi-Fe0MFAvN6_eO2gWJpTUAogdISCeO9g5fhGh4KHGh2cy44dVlrT29uUVRtVFM5YWx1VkE2T1F1cFE
issue_time          2025-08-10T09:54:47.73825+02:00
meta                <nil>
num_uses            0
orphan              false
path                auth/token/create
policies            [default secret-management]
renewable           true
ttl                 59m46s
type                service

To better understand these attributes, they can be grouped as follows:

  • Identification
    • id: Technical id, which is required when using the Vault CLI or accessing the Vault API endpoints.
    • type: Three technical types are distinguished: service, batch, and recovery
    • accessor: A token accessor is an intermediate entity, it provides all of the above information, but not the actual token itself. Therefore, an accessor can not be used for authentication, it can not be used to perform actions on a Vault instance
    • entity_id: Entities are accounts representing human users or machines, grouping several alias definitions into one representation. To keep track of tokens created for entities, a static association can be configured at token creation time.
  • Properties
    • num_uses: Upper limit of renewal actions for renewable tokens.
    • orphan: Tokens created via the CLI or API happen in the context of a parent token and create associated child tokens. Orphaned tokens are independent tokens, and this property reflects their status
    • policies: Lists the policy names exhibited by the token.
    • renewable: Property of the token specifying if the validity can be extended before the current TTL expires
  • Validity
    • expire_time: Time string formatted expiration time of the token.
    • explicit_max_ttl: All authentication methods have a default TTL that is passed to created tokens. This value overrides the default and sets a non-modifiable absolute time limit after which the token expires
    • ttl: Duration after which the token expires
  • Technical information
    • creation_time: Unix epoch timestamp encoding an absolute value
    • creation_ttl: The initially defined Time-To-Live (TTL) after which the token expires
    • issue_time: Time string formatted creation time.
    • path: The API path from which this token was created.
  • Metadata
    • display_name: Custom non-technical name for the token to be better distinguished by operators working with vault.
    • meta: Arbitrary text value containing information for human operators. When structured as JSON format, the token lookup command will renders this data properly.

Token Types

Although the official documentation distinguishes into three token types only, further exploration and utilization of Vault necessitates a more fine-grained terminology. I suggest to define each token in terms of three properties: type, capabilities, and origin.

  • Type
    • service Service tokens are written to the Vault storage and intended for validity of several hours or days. They are identified with an hvs prefix.
    • batch: Only exist in-memory of the Vault instance, for timespans of a few seconds or minutes. Identified by the hvb prefix.
    • recovery: Temporary tokens used for troubleshooting when a Vault server does not start, prefix with hvr. They provide direct access to the storage layer.
  • Capabilities
    • The tokens can form complex hierarchical relationship, being parent, child or orphan.
    • Can be renewable for a defined number of times or unlimited.
    • All renewable tokens require an explicit CLI command or API call, but tokens with the periodic property are renewed automatically.
    • The Cubbyhole secrets engine stores one-time access only paths on the storage layer, and this path is unique and can be attached to a token by response-wrapping. This token does not contain the secret itself, but the unique storage path
  • Origin
    • Most tokens are created as the result of an authentication method, creating access to Vault API paths as defined in their policies
    • By using specific CLI or API methods, managed tokens can be created, with full control about their policies, and full configurability of their properties

The properties define a morphological table:

| Type         | service        | batch     | recovery |
| Capabilities | hierarchical   | renewable | periodic | response-wrapping |
| Origin       | authentication | managed   |

Auth Token

| Type         | service        |
| Capabilities | renewable      |
| Origin       | authentication |

All authentication method issue service tokens that include all configured properties like the TTL and policies. Some methods also create limited renewable tokens. Auth tokens are always parent tokens, and like other service tokens, they provide a token accessor.

Managed Token

| Type         | service        | 
| Capabilities | hierarchical   | renewable | periodic | response-wrapping |
| Origin       | managed        |

Managed tokens are a service token type that provides the greatest amount of properties. They are created from a parent token, either an auth token or another managed token, and can form complex hierarchies of parent, child, or orphan tokens. Furthermore, they can be made limited renewable or unlimited renewable. When given the periodic property, they form the special type periodic service token: renewed automatically at the end of their TTL to their defined maximum period value. Finally, the cubbyhole secrets engine can only be accessed with this token type. All managed tokens also have a token accessor

Batch tokens

| Type        | batch     | 
| Origin      | managed   |

Applications that impose a high-frequency on token creation, and especially when the token only need to be valid for mere seconds or minutes, batch tokens should be used. They need to be created via the CLI or API, and need an auth token or managed token as their parent. They can not form relationships, and are not renewable - they solely serve for providing the policy defined accesses to other API paths.

Root Token

| Type        | service |

The default enabled token authentication engine issues this special type of token. It is paired with the root policy, with which complete access to all Vault functions is provided. Root tokens are created initially following the vault operator init command, and should be used only for initial setup, and then revoked. The second option to create these tokens for a running vault server is the vault operator generate-root init command. Similar to unsealing a Vault instance, a consecutive number of key shares need to be entered, which returns the encoded root token to be decoded with an OTP value generated with the first command sequence.

Recovery Tokens

| Type        | recovery |

These tokens are applicable for a narrow use case only. When a Vault instance or cluster does not start, it can be put into a recovery mode. In this state, a recovery token can be generated with a similar process to that of creating a root token. With this recovery token, direct access to the Vault storage layer is provided via the sys/raw endpoint, effectively exposing the mount paths of Vault internal plugins and installed plugins, including secrets engines. Also see the /sys/raw endpoint documentation.

Conclusion

Tokens are fundamental entities in Hashicorp Vault. From the moment of initializing a Vault server, tokens govern the access for operational tasks and secrets a like. In this blog article, you gained a compact and complete understanding of tokens in Vault. Technically, three types of tokens can be distinguished: Service tokens with all properties, lightweight and non-persisted batch tokens, and recovery tokens used only in case of emergency. These types can be further distinguished by viewing their origin and capabilities. Auth tokens are the result of using an authentication method, and managed tokens are created via the CLI or API. Only managed tokens give access to all properties, including free assignment of policies and roles, configuring number of allowed renewals, and setting an absolute upper lifetime TTL. The next article expands this knowledge and shows all CLI and API methods for the complete token lifecycle.


Previous: Hashicorp Vault: Secret Management Engines