Tokens
Summary: Tokens are the core authentication artifact in OpenBao. Every authenticated request carries one. They map to a policy set and (for service tokens) to a lease.
Sources: raw/docs/concepts/tokens.md, raw/docs/auth/token.md.
Last updated: 2026-05-19
Token format
A token is <prefix>.<body> where the prefix encodes the type:
s.— service tokenb.— batch tokenr.— recovery token
Regex: [sbr]\.[a-zA-Z0-9]{24,} (source: raw/docs/concepts/tokens.md).
The structure is officially opaque — relying on internals will break.
Service vs batch
Service tokens are the default. They are persisted, renewable, revocable, and carry a lease. They support children and orphans.
Batch tokens are encrypted blobs containing their own claims — not stored server-side. They are cheap to create, can’t be renewed, and are revoked only by expiring. Useful for very high-volume short-lived workloads (source: raw/docs/concepts/tokens.md).
The token store
The token auth method is special: it’s responsible for creating and storing tokens, cannot be disabled, and has no login endpoint — every action requires an existing token (source: raw/docs/auth/token.md, raw/docs/concepts/tokens.md).
Root tokens
Root tokens hold the root policy → unlimited access. Three ways to obtain one:
- The initial token from
bao operator init(no expiration). - By using another root token.
- By
bao operator generate-rootwith a quorum of unseal-key holders.
Recommendation: use root only for initial bootstrap or emergencies, then revoke immediately (source: raw/docs/concepts/tokens.md).
Hierarchies and orphans
Tokens form a tree by default — revoking a parent revokes all children and their leases. Orphan tokens have no parent and survive their creator’s revocation. Created via auth/token/create-orphan, or auth/token/create with no_parent=true and sudo, or via token roles (source: raw/docs/concepts/tokens.md).
TTL and renewal
Service tokens have a TTL and a max TTL. Clients renew with bao token renew (or via lifetime-watcher in SDKs). Renewals are advisory — the auth method can cap the increment (source: raw/docs/concepts/lease.md, raw/docs/concepts/auth.md).