Learn Secret Management - Lease Management, Renewal & Emergency Revocation
Managing the lifecycle of dynamic secrets in OpenBao: understanding Lease IDs and TTLs, extending the lifetime with bao lease renew, and revoking access instantly with bao lease revoke and revoke by prefix when credentials leak.
#Introduction
In episode 8 you obtained tokens through various auth methods. Episode 9 discusses what happens to a dynamic secret after it is born: every credential issued by OpenBao — whether the database credentials from episode 4 or the certificates from episode 6 — carries a lease that determines how long it lives. Understanding leases means understanding when to renew, and more importantly, how to destroy access instantly when needed.
#Understanding Lease and TTL
A lease is a time contract between OpenBao and the secret holder. Every dynamic secret — credentials created specifically for you, such as the Postgres user from database/creds/my-role — is represented by a unique Lease ID and a TTL (Time To Live).
Reading a dynamic secret shows the lease metadata:
bao read database/creds/my-roleThe output contains three important things:
lease_id— the unique credential identity, for exampledatabase/creds/my-role/NGQwYzA....lease_duration— how many seconds the lease remains valid (TTL).renewable— whether the lease can be renewed or not.
When the TTL runs out, OpenBao automatically destroys the credential — the Postgres user above is removed from the database. This is why dynamic secrets are so safe: their lifetime is limited and system-controlled, not left to linger forever.
#Secret Lease vs Token TTL
People often mix up a secret lease with a token TTL. In fact they are different concepts:
| Aspect | Dynamic Secret Lease | Token TTL |
|---|---|---|
| Object | One credential instance (e.g. a DB user) | The authentication session of a user or machine |
| Identity | Lease ID | Token value |
| Renewal | bao lease renew <id> | bao token renew |
| Revocation | bao lease revoke <id> | bao token revoke |
| Effect of expiry | Credential destroyed by the system | Token can no longer be used |
In short: the token is the front door, the lease is the contract for what's inside. Revoking a token does not automatically destroy leases already held, and vice versa. Both need to be managed separately.
#Lease Renewal
When a job runs longer than the TTL, you can renew the lease as long as it is still renewable and not yet expired:
bao lease renew database/creds/my-role/NGQwYzA...To set a specific renewal duration, add the -increment option:
bao lease renew -increment=1h database/creds/my-role/NGQwYzA...bao lease renew -increment=1h database/creds/my-role/NGQwYzA... attempts to extend the lease for 1 hour — the final result is still capped by the max_ttl of the engine or role. A well-behaved application renews its leases periodically, rather than waiting until they are nearly expired.
#Instant Access Revocation
If there is any indication of leaked credentials, don't wait for the TTL to expire. Revoke immediately:
bao lease revoke database/creds/my-role/NGQwYzA...That command instantly destroys a single credential. However, in a real incident you usually don't know exactly which Lease ID leaked — what you know is that database credentials across the entire application could be exposed. For this case use revoke by prefix:
bao lease revoke -prefix database/credsbao lease revoke -prefix database/creds revokes all leases starting with that prefix — meaning every database credential ever issued by the database engine is instantly destroyed. This is the emergency button most often used during incident response.
Caution
Revoke by prefix is highly destructive. Revoking the database/creds prefix will cut off all applications using those credentials at the same time. Make sure applications are designed to fetch new credentials (retry and re-request), not rely on a single static connection — otherwise, a total outage is unavoidable.
#Monitoring Active Leases
Before revoking, you need to know which leases are currently circulating. All leases can be listed per prefix:
bao lease list database/creds
bao lease list database/creds/my-rolebao lease list database/creds shows all leases currently active under that prefix. This is very useful during an incident: you can see how many credentials are exposed before deciding whether to use per-lease revoke or revoke by prefix. Combine it with bao lease renew to extend only the ones still needed.
#Simulating a Leak Scenario
Let's string it all together in one incident flow:
- A database credential leaks into an application log.
- The team decides all credentials from the
databaseengine must be replaced. - Run
bao lease revoke -prefix database/credsto destroy them all. - Every application requesting a new connection automatically receives a new user and password from
database/creds/my-role. - The old credentials are no longer valid in Postgres — no one can use them anymore.
This flow shows the true power of dynamic secrets: instant mass revocation, without touching a single configuration file. What you need to maintain is that applications are ready to accept new credentials.
#Conclusion
In this episode 9 you understood leases as the time contract of dynamic secrets: the Lease ID and TTL structure, the difference between secret leases and token TTLs, renewal via bao lease renew, and instant revocation with bao lease revoke and revoke by prefix for database/creds.
Key takeaways:
- Every dynamic secret has a Lease ID and TTL — once expired, the credential is destroyed by the system.
- Renew before expiry — an expired lease can no longer be
renew-ed. - Revoke by prefix for major incidents — one command wipes out an entire class of credentials.
- Applications must be ready to fetch new credentials — resilience depends on retries, not static connections.
In the next episode, episode 10, we take all these concepts out of the OpenBao server and into the real world: web application integration with Node.js, Go, Python, and Laravel — both via the direct REST API and via environment injection without changing source code.