/sys/leases

The /sys/leases endpoints are used to view and manage leases in OpenBao.

Read lease

This endpoint retrieve lease metadata.

Method	Path
POST	/sys/leases/lookup

Parameters

• lease_id (string: <required>) – Specifies the ID of the lease to lookup.

Sample payload

{
  "lease_id": "auth/userpass/login/user/h5a2..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/lookup

Sample response

{
  "data": {
    "expire_time": "2024-03-07T20:34:02.005655614+01:00",
    "id": "auth/userpass/login/user/h5a2d7506918f459d022267a3351666b35bd8b5d6d39b0bcfe14927c0e4464225",
    "issue_time": "2024-02-04T20:34:02.005663311+01:00",
    "last_renewal": null,
    "renewable": true,
    "ttl": 2764397
  }
}

List leases

This endpoint returns a list of lease ids.

This endpoint requires 'sudo' capability.

Method	Path
LIST	/sys/leases/lookup/:prefix

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/leases/lookup/auth/userpass/login/user/

Sample response

{
  "data": {
    "keys": [
      "h5a2d7506918f459d022267a3351666b35bd8b5d6d39b0bcfe14927c0e4464225"
    ]
  }
}

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
POST	/sys/leases/renew

Parameters

• lease_id (string: <required>) – Specifies the ID of the lease to extend. This parameter can either be specified in a json request, as shown below, or provided as a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence.

• increment (int: 0) – Specifies the requested amount of time (in seconds) to extend the lease.

Sample payload

{
  "lease_id": "auth/userpass/login/user/h5a2...",
  "increment": 1800
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/renew

Sample response

{
  "lease_id": "auth/userpass/login/user/h5a2...",
  "renewable": true,
  "lease_duration": 2764790
}

Revoke lease

This endpoint revokes a lease immediately.

Method	Path
POST	/sys/leases/revoke

Parameters

• lease_id (string: <required>) – Specifies the ID of the lease to revoke. This parameter can either be specified in a json request, as shown below, or provided as a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence.
• sync (bool: false) - Instead of the default behaviour of queueing the lease revocation, sync=true will revoke the lease immediately and only return once complete.

Sample payload

{
  "lease_id": "postgresql/creds/readonly/abcd-1234..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/leases/revoke

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, OpenBao 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
POST	/sys/leases/revoke-force/:prefix

Parameters

• prefix (string: <required>) – Specifies the prefix to revoke. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-force/auth/userpass

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
POST	/sys/leases/revoke-prefix/:prefix

Parameters

• prefix (string: <required>) – Specifies the prefix to revoke. This is specified as part of the URL.
• sync (bool: false) - Instead of the default behaviour of queueing the lease revocations, sync=true will revoke ths leases immediately and only return once complete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/auth/userpass

Tidy leases

This endpoint cleans up the dangling storage entries for leases: for each lease entry in storage, OpenBao 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/tidy

Lease counts

This endpoint returns the total count of a type of lease, as well as a count per mount point. Note that it currently only supports type "irrevocable".

This can help determine if particular endpoints are disproportionately resulting in irrevocable leases.

Parameters

• type (string: <required>) - Specifies the type of lease.
• include_child_namespaces (bool: false) - Specifies if leases in child namespaces should be included in the result.

Method	Path
GET	/sys/leases/count

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/leases/count \
    -d type=irrevocable

Leases list

This endpoint returns the total count of a type of lease, as well as a list of leases per mount point. Note that it currently only supports type "irrevocable".

This can help determine if particular endpoints or causes are disproportionately resulting in irrevocable leases.

Parameters

• type (string: <required>) - Specifies the type of lease.
• include_child_namespaces (bool: false) - Specifies if leases in child namespaces should be included in the result
• limit (string: "") - Specifies the maximum number of leases to return in a request. To return all results, set to none. If not set, this API will return a maximum of 10,000 leases. If not set to none and there exist more leases than limit, the response will include a warning.

Method	Path
GET	/sys/leases

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/leases \
    -d type=irrevocable