Intekhab Rizvi

Chapter 15 / 28

Leasing, TTL, and Vault's Secret Lifecycle

HashiCorp Vault For Beginners6 min read

Now that you've seen Vault dynamically generate MySQL credentials for you (magic, right?), you might be wondering:

  • How long do those credentials last?
  • What happens when they expire?
  • Can I revoke them early?
  • Can I extend them?
  • Can I restrict how many times they’re used?

This chapter dives into Vault's leasing mechanism — the core engine that governs how long secrets live, how they're revoked, and how they behave after being handed out.

What Is a Lease?

When Vault generates a dynamic secret (like our MySQL credentials), it also generates a lease. A lease is like a signed contract between you and Vault:

"Here’s your secret. You're allowed to use it for X seconds or Y number of times. After that, it's gone."

Every lease has:

  • A lease_id
  • A lease_duration (TTL)
  • A renewable flag
  • Optionally, a num_uses limit

Example:

lease_id:       database/creds/readonly-role/abc123456
lease_duration: 1h
renewable:      true

TTL (Time to Live)

TTL determines how long the secret remains valid. After the TTL, Vault automatically revokes the secret.

TTL can be configured:

  • On the secret engine
  • On the role
  • At the Vault server level

Example during role creation:

vault write database/roles/readonly-role \
    db_name=my-mysql-database \
    creation_statements="..." \
    default_ttl="1h" \
    max_ttl="24h"
  • default_ttl: Applies to leases unless manually overridden.
  • max_ttl: The maximum TTL even if a lease is renewed multiple times.

3. num_uses: Expire After X Uses

Besides TTL, Vault allows you to set a num_uses on a role — which limits how many times a generated secret can be used, regardless of the TTL.

Once the credential is used the specified number of times, Vault automatically revokes the lease.

This is incredibly useful for:

  • One-time login credentials
  • Scripts or apps that only need brief access
  • Preventing credential reuse in CI/CD pipelines

Here’s how to set it correctly during role creation:

vault write database/roles/readonly-role \
    db_name=my-mysql-database \
    creation_statements="..." \
    default_ttl="1h" \
    max_ttl="24h"
    num_uses=1

num_uses : Every time a secret is issued using this role, that username/password will expire after one use — no matter how much time is left on the TTL.

You can verify this behavior by issuing credentials:

vault read database/creds/readonly-role

Try using the username and password once — it’ll work.
Try again? It’s already revoked.

4. Viewing Active Leases

To list leases for a role:

vault list sys/leases/lookup/database/creds/readonly-role

To look up lease details:

vault lease lookup <lease_id>

5. Renewing a Lease

If the lease is renewable and TTL hasn’t hit max_ttl, you can extend the lease:

vault lease renew <lease_id>

This is especially useful for long-running applications or sessions that don’t want to re-authenticate.

6. Revoking a Lease

Need to shut off access early? Use:

vault lease revoke <lease_id>

This invalidates the associated secret and revokes access on the spot.

You can also revoke everything under a path:

vault lease revoke -prefix database/creds/readonly-role

7. Lease vs Static Secrets

Let’s make the distinction clear:

FeatureStatic Secret (e.g., KV)Dynamic Secret (e.g., DB)
Manually managedYesNo
Automatically expiredNoYes
TTL-basedNoYes
num_uses supportNoYes
Auto-revocationNoYes

8. Why Leases Matter

This leasing model gives you control, auditability, and peace of mind. Imagine:

  • An app gets hacked. Revoke the lease = instant kill switch.
  • You want a password to expire after one use. num_uses = 1.
  • You rotate secrets every hour. TTL handles it for you.

Vault isn’t just storing secrets. It’s managing their lifecycle securely, on your behalf.