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:

​
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:
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>.

​
Step 1: Initialize Root Generation

Kick off the process to obtain a Nonce and OTP:
  • 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):
Repeat until the threshold is reached. After the final key:

​
Step 3: Decode the Root Token

Use the OTP and the encoded token to reveal the new root token:
Authenticate and then revoke promptly:

​
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