Vault Leases · Topic 1 of 2

Lease IDs and Renewing Leases

Vault Associate (003): what a lease is, why the lease ID matters, and how vault lease renew and the increment extend a dynamic secret before its TTL ends.

  • 4 min
In a nutshell
  • Vault creates a lease for each dynamic secret and each service token.
  • A lease holds a TTL, renewability and related details; the ID is its unique handle.
  • Lease IDs begin with the request path of the secret that produced them.

What it is

A lease is metadata that Vault attaches to a secret. It records how long the secret is valid (its TTL), whether it can be renewed, and related details. Vault creates a lease for every dynamic secret and every service token.

The lease ID is the unique name of that lease. It is returned when you read a dynamic secret, and you use it to look up, renew or revoke that one secret later.

Clientvault readDatabase enginecreates credentialsLease ID and TTLreturned to clientvault lease renewNew TTL

How it works

What a lease gives you

Vault promises the secret is valid for the lease duration. When the lease expires, Vault can revoke the secret automatically, and the consumer can no longer rely on it. For example, with the AWS secrets engine, the access keys are deleted from AWS when the lease is revoked.

All dynamic secrets have a lease, even ones meant to last a long time, so that consumers must check in regularly. The key/value engine does not issue leases, since its secrets are static, although it sometimes returns a lease duration.

The lease ID

Lease IDs begin with the request path of the secret. A read of database/creds/readonly gives an ID that starts with that path.

vault read database/creds/readonly

The output includes lease_id, lease_duration, lease_renewable, username and password. The ID looks like database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83.

Why the path prefix matters: it identifies which engine and role issued the secret, and it lets an operator act on a whole group of leases by prefix (see the revoking page). To inspect one lease, use its ID.

vault lease lookup database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83

Lookup shows the ID, issue time, expire time, last renewal, whether it is renewable, and the TTL. The API equivalent is POST /sys/leases/lookup with lease_id.

Renewing a lease

Renewal extends how long the secret can be used and does not change the secret itself. The consumer must renew before the TTL runs out.

vault lease renew database/creds/readonly/27e1b9a1-27b8-83d9-9fe0-d99d786bdc83
vault lease renew -increment=3600 <lease-id>

The output shows lease_id, lease_duration and lease_renewable. The API is POST /sys/leases/renew with lease_id and an optional increment in seconds.

The increment

The increment is the time you request, counted from now and not from the end of the current TTL. So -increment=3600 asks for a TTL of one hour from the moment of renewal.

It is advisory. The backend may ignore it or cap it, so always read the response to see the lease you actually got. A shorter increment lets credentials expire sooner, which cleans up resources earlier.

The max_lease_ttl server setting caps lease duration for tokens and secrets, and it defaults to 768h (32 days). A mount can override it with the -max-lease-ttl flag when tuned.

Token leases are different: they cannot be renewed through sys/leases/renew. Use vault token renew, which is covered in the tokens chapter.

How the exam asks about this

  • "Which value do you need to renew a database credential?" The lease ID.
  • "An app asks to renew a lease for 1 hour but the engine allows less." Vault grants the lesser time, since the increment is advisory.
  • "Which secrets engine does not return leases for its secrets?" Key/Value, because the secrets are static.

What to remember for the exam

  • Vault creates a lease for each dynamic secret and each service token.
  • A lease holds a TTL, renewability and related details; the ID is its unique handle.
  • Lease IDs begin with the request path of the secret that produced them.
  • vault lease renew <lease-id> extends a lease, and -increment requests a specific duration.
  • The increment counts from the time of renewal and Vault may grant less.
  • vault lease lookup <lease-id> shows the TTL and whether the lease is renewable.
Watch out

Renewing a lease does not rotate or change the secret. If a question says the credential must change, the answer is to revoke it and read a new one.

Common mistakes

Renewing with the secret instead of the ID. The commands take the lease ID, not the username, password or token. Copy lease_id from the output of the read.

Thinking the increment is added to the current TTL. It is a request counted from now. A request of one hour does not give the remaining time plus one hour.

Expecting every secret to have a lease. Dynamic secrets do, but static key/value secrets do not need one, so there is nothing to renew.

Check yourself

  • What is the purpose of a lease ID?

    It uniquely identifies a lease, so you can look up, renew or revoke the secret it covers. It also begins with the path that issued the secret.

  • Does vault lease renew -increment=1h always give a one-hour lease?

    No. The increment is advisory and counted from now, and the backend can grant less.

  • Which command shows whether a lease is still renewable?

    vault lease lookup <lease-id>, which returns the issue time, expire time, last renewal, renewable flag and TTL.

Topic 1 of 2 in Vault Leases

Test yourself on Vault Leases

The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.