Vault Tokens · Topic 2 of 3
Root Tokens and Token Accessors
Vault Associate (003): what root tokens are for, how to generate and revoke them, and what a token accessor can do: lookup, capabilities, renew and revoke.
- 4 min
- A root token has the
rootpolicy and can perform any action. - Only a root token can have no expiration (TTL of 0); the initial one from
vault operator inithas none. - Use root tokens for initial setup or emergencies only, then revoke them.
What it is
A root token is a token with the root policy, so it can do anything in Vault. It is the only kind of token that can be set to never expire. Because it is so powerful, you use it briefly and then get rid of it.
A token accessor is a second identifier returned when a service token is created. It refers to the token and allows a limited set of actions, but it can never be used to log in or read secrets.
How it works
Root token uses and lifecycle
The first root token comes from vault operator init and has no expiration. Use it only for initial setup, such as configuring auth methods and policies so administrators can work with narrower tokens, or in an emergency. Revoke it as soon as you are done.
There are three ways to create a root token:
| Method | Notes |
|---|---|
vault operator init | The initial root token, no expiration |
| An existing root token | A root token that has an expiration cannot create one that never expires |
vault operator generate-root | Needs a quorum of unseal key holders |
With auto unseal, the quorum is made of recovery keys instead of unseal keys.
Generating a new root token
Generation is a shared effort, so no single person can mint a root token alone.
vault operator generate-root -generate-otp
vault operator generate-root -init -otp=<otp>
vault operator generate-root
vault operator generate-root -decode=<encoded-token> -otp=<otp>
The first command makes a one-time password (OTP). The second starts the attempt. The bare generate-root is run once per key holder, each entering a key, until the quorum is met and an encoded token appears.
The last command decodes it with the same OTP. -status shows progress and -cancel resets an attempt.
What an accessor can do
An accessor lets you manage a token you do not hold. It supports four actions:
| Action | Command or path |
|---|---|
| Look up properties (not the token ID) | vault token lookup -accessor <accessor> |
| Look up capabilities on a path | POST /sys/capabilities-accessor |
| Renew the token | vault token renew -accessor <accessor> |
| Revoke the token | vault token revoke -accessor <accessor> |
curl --header "X-Vault-Token: $VAULT_TOKEN" --request POST \
--data '{"accessor":"<accessor>","paths":["secret/foo"]}' \
$VAULT_ADDR/v1/sys/capabilities-accessor
The permissions of the caller matter, not those of the token behind the accessor. Listing every accessor uses LIST auth/token/accessors and needs sudo.
Typical use: a scheduler stores the accessor for each job it launched. When the job ends, it revokes that token and its leases by accessor, and never needed the token itself. Batch tokens have no accessor.
How the exam asks about this
- "An auditor must find out when a token expires but must not receive the token." Use
vault token lookup -accessor. The output leaves out the token ID. - "Which token type should be revoked right after initial setup?" The root token.
- "How do you get a new root token when none exists?"
vault operator generate-root, with a quorum of key holders.
What to remember for the exam
- A root token has the
rootpolicy and can perform any action. - Only a root token can have no expiration (TTL of 0); the initial one from
vault operator inithas none. - Use root tokens for initial setup or emergencies only, then revoke them.
vault operator generate-rootcreates a new root token and needs a quorum of unseal key holders, or of recovery key holders with auto unseal.- An accessor can look up properties, look up capabilities, renew and revoke, and cannot read secrets.
- An accessor lookup never returns the token ID itself.
An accessor is not a login credential. Holding one lets you manage a token, not use it, but accessor-based revoke can still disrupt many clients, which is why listing accessors needs sudo.
Common mistakes
Keeping the root token for daily work. The advice is to revoke it after setup and generate a new one only when needed. A standing root token is the opposite of that.
Treating the accessor as a second token. You cannot send an accessor as X-Vault-Token to read a secret. It only supports lookup, capabilities, renew and revoke.
Thinking one person can run generate-root. The process needs a quorum of unseal key holders (recovery keys with auto unseal), so it is built to need several people.
Check yourself
Which kind of token can be created without an expiration?
Only a root token, and the initial root token from
vault operator inithas none. Every other token has a TTL, and a periodic token avoids expiry only by being renewed within each period.What four things can you do with a token accessor?
Look up the token's properties, look up its capabilities on a path, renew it, and revoke it. The lookup does not include the token ID.
How do you create a new root token after the old one was revoked?
Run
vault operator generate-root, with a quorum of unseal key holders (or recovery key holders when auto unseal is used) submitting their keys.
Topic 2 of 3 in Vault Tokens
Test yourself on Vault Tokens
The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.