open-vault/website/content/api-docs/system/leases.mdx

---
layout: api
page_title: /sys/leases - HTTP API
description: The `/sys/leases` endpoints are used to view and manage leases.
---

# `/sys/leases`

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

## 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

```json
{
  "lease_id": "aws/creds/deploy/abcd-1234..."
}
```

### Sample Request

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

### Sample Response

```json
{
  "id": "auth/token/create/25c75065466dfc5f920525feafe47502c4c9915c",
  "issue_time": "2017-04-30T10:18:11.228946471-04:00",
  "expire_time": "2017-04-30T11:18:11.228946708-04:00",
  "last_renewal_time": null,
  "renewable": true,
  "ttl": 3558
}
```

## List Leases

This endpoint returns a list of lease ids.

**This endpoint requires 'sudo' capability.**

| Method | Path                         |
| :----- | :--------------------------- |
| `LIST` | `/sys/leases/lookup/:prefix` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/leases/lookup/aws/creds/deploy/
```

### Sample Response

```json
{
  "data": {
    "keys": ["abcd-1234...", "efgh-1234...", "ijkl-1234..."]
  }
}
```

## 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

```json
{
  "lease_id": "aws/creds/deploy/abcd-1234...",
  "increment": 1800
}
```

### Sample Request

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

### Sample Response

```json
{
  "lease_id": "aws/creds/deploy/abcd-1234...",
  "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

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

### Sample Request

```shell-session
$ 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, 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                               |
| :----- | :--------------------------------- |
| `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

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-force/aws/creds
```

## 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

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/aws/creds
```

## 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

```shell-session
$ 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.

This endpoint was added in Vault 1.8.

### 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

```shell-session
$ 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.

This endpoint was added in Vault 1.8.

### 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

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