/sys/leases
The /sys/leases
endpoints are used to view and manage leases in Vault.
Read Lease
This endpoint retrieve lease metadata.
Method | Path |
---|---|
PUT | /sys/leases/lookup |
Parameters
lease_id
(string: <required>)
– Specifies the ID of the lease to lookup.
Sample Payload
Sample Request
Sample Response
List Leases
This endpoint returns a list of lease ids.
This endpoint requires 'sudo' capability.
Method | Path |
---|---|
LIST | /sys/leases/lookup/:prefix |
Sample Request
Sample Response
Renew Lease
This endpoint renews a lease, requesting to extend the lease. Token leases cannot be renewed using this endpoint, use instead the auth/token/renew endpoint.
Method | Path |
---|---|
PUT | /sys/leases/renew |
Parameters
lease_id
(string: <required>)
– Specifies the ID of the lease to extend. This can be specified as part of the URL or as part of the request body.increment
(int: 0)
– Specifies the requested amount of time (in seconds) to extend the lease.
Sample Payload
Sample Request
Sample Response
Revoke Lease
This endpoint revokes a lease immediately.
Method | Path |
---|---|
PUT | /sys/leases/revoke |
Parameters
lease_id
(string: <required>)
– Specifies the ID of the lease to revoke.
Sample Payload
Sample Request
Revoke Force
This endpoint revokes all secrets or tokens generated under a given prefix
immediately. Unlike /sys/leases/revoke-prefix
, this path ignores backend errors
encountered during revocation. This is potentially very dangerous and should
only be used in specific emergency situations where errors in the backend or the
connected backend service prevent normal revocation.
By ignoring these errors, Vault abdicates responsibility for ensuring that the issued credentials or secrets are properly revoked and/or cleaned up. Access to this endpoint should be tightly controlled.
This endpoint requires 'sudo' capability.
Method | Path |
---|---|
PUT | /sys/leases/revoke-force/:prefix |
Parameters
prefix
(string: <required>)
– Specifies the prefix to revoke. This is specified as part of the URL.
Sample Request
Revoke Prefix
This endpoint revokes all secrets (via a lease ID prefix) or tokens (via the
tokens' path property) generated under a given prefix immediately. This requires
sudo
capability and access to it should be tightly controlled as it can be
used to revoke very large numbers of secrets/tokens at once.
This endpoint requires 'sudo' capability.
Method | Path |
---|---|
PUT | /sys/leases/revoke-prefix/:prefix |
Parameters
prefix
(string: <required>)
– Specifies the prefix to revoke. This is specified as part of the URL.
Sample Request
Tidy Leases
This endpoint cleans up the dangling storage entries for leases: for each lease entry in storage, Vault will verify that it has an associated valid non-expired token in storage, and if not, the lease will be revoked.
Generally, running this is not needed unless upgrade notes or support personnel suggest it. This may perform a lot of I/O to the storage method so should be used sparingly.
Method | Path |
---|---|
POST | /sys/leases/tidy |
Sample Request