Skip to main content
When standard authentication methods fail, regenerating a root token grants temporary superuser access. In this guide, you’ll learn what a root token is, how to revoke the initial token, and step-by-step instructions for generating a new one using unseal (recovery) keys.

​
What Is a Root Token?

A root token is Vault’s superuser credential. It’s bound to the built-in root policy—which cannot be modified or deleted—and grants unrestricted access across your Vault cluster.
The image is an informational slide about root tokens, explaining their unlimited access to Vault, lack of expiration, and guidelines for their use and revocation. It also includes a Vault certification badge and a cartoon character at the bottom.
Key characteristics:
CharacteristicDescription
No TTLNever expires; valid indefinitely
Usage scopeOnly for initial setup or critical emergencies
Immediate revocation neededRevoke the root token as soon as tasks are complete
ImmutableCannot be altered or deleted

​
Initial Root Token and Revocation

Immediately after initializing Vault, your only authentication method is the initial root token. Once you enable and configure other auth backends (e.g., LDAP, AppRole, Kubernetes) and create policies, revoke this token to minimize risk: 
vault token revoke s.dhtIk8VsE3Mj61PuGP3ZfFrg
# Success! Revoked token (if it existed)
The token prefix (s. or hvs.) varies by Vault version.

​
Emergency Scenario: Broken Authentication

Imagine Vault uses corporate LDAP for operator logins:
  1. Operator logs in via LDAP
  2. Vault validates credentials against the LDAP server
  3. A network change or firewall misconfiguration breaks LDAP connectivity
The image illustrates a broken authentication workflow involving a Vault operator, LDAP authentication, and corporate LDAP servers, highlighting issues with authentication and validation. It poses the question of what happens if there is no working authentication method to fix the problem.
Without a valid auth method or a root token, you cannot update the LDAP backend. In such emergencies, you can regenerate a root token by leveraging your unseal (recovery) keys—ensuring no single individual can generate it alone.

​
Regenerating a Root Token

Root token regeneration follows the same quorum-based approach as Vault unsealing. You’ll:
  1. Initialize the generation process.
  2. Have each key holder submit their unseal key.
  3. Decode the new root token with the one-time password (OTP).
The image is an instructional guide on regenerating a root token using unseal/recovery keys, with three steps outlined: initializing root generation, each key holder running 'generate root' with their unseal key, and decoding the generated root token. It includes a Vault certification badge and a cartoon character at the bottom.

​
Command Options

Below are the primary flags for vault operator generate-root:
The image is a slide about Vault Initialization, showing command options and their descriptions for generating a root token. It includes a table with options like -generate-otp, -init, and -decode=<string>.
FlagDescription
-initStart root generation; outputs a nonce and OTP.
-statusView progress (Progress X/Y).
-cancelAbort the generation operation.
-otpSupply the one-time password when decoding the token.
-decodeProvide the encoded token string for decoding.

​
Step 1: Initialize Root Generation

Kick off the process to obtain a Nonce and OTP: 
vault operator generate-root -init

A One-Time-Password has been generated for you and is shown in the OTP field.
Keep this OTP secure; it’s required to decode the new root token.
Nonce        5b6e3831-2a45-4695-7757-5810074d36c8
Started      true
Progress     0/3
Complete     false
OTP          E87jF6ZeJo8NjWvytl7mvKLEr
OTP Length   26
  • Nonce: Share with key holders.
  • OTP: Confidential; do not expose.
  • Progress: Tracks submissions (e.g., 0/3 keys submitted).
Guard the OTP carefully. Anyone with the OTP and the final encoded token can reconstruct the root token.

​
Step 2: Key Holders Submit Unseal Keys

Each key holder runs the command (no flags): 
vault operator generate-root

Root generation operation nonce: 5b6e3831-2a45-4695-7757-5810074d36c8
Unseal Key (hidden input):
Nonce       5b6e3831-2a45-4695-7757-5810074d36c8
Started     true
Progress    1/3
Complete    false
Repeat until the threshold is reached. After the final key: 
vault operator generate-root

Nonce          5b6e3831-2a45-4695-7757-5810074d36c8
Started        true
Progress       3/3
Complete       true
Encoded Token  G2NeKUZgXTsYYxILAC9ZFBguPw9ZBovFAs

​
Step 3: Decode the Root Token

Use the OTP and the encoded token to reveal the new root token: 
vault operator generate-root \
  -otp="E87jF6ZeJo8NjWvytl7mvKLEr" \
  -decode="G2NeKUZgXTsYYxILAC9ZFBguPw9ZBovFAs"

Root token: hvs.gXtT3uq9teYf0ZnFQH6hOiw8
Authenticate and then revoke promptly: 
vault login hvs.gXtT3uq9teYf0ZnFQH6hOiw8
vault token revoke hvs.gXtT3uq9teYf0ZnFQH6hOiw8
# Success! Revoked token (if it existed)

​
Best Practices

  • Always revoke root tokens immediately after use.
  • Limit the number of key holders and enforce MFA for key storage.
  • Rotate recovery keys and OTP lifetimes regularly.

​
References

Watch Video