1---
2layout: "api"
3page_title: "/sys/leases - HTTP API"
4sidebar_title: "<code>/sys/leases</code>"
5sidebar_current: "api-http-system-leases"
6description: |-
7  The `/sys/leases` endpoints are used to view and manage leases.
8---
9
10# `/sys/leases`
11
12The `/sys/leases` endpoints are used to view and manage leases in Vault.
13
14## Read Lease
15
16This endpoint retrieve lease metadata.
17
18| Method   | Path                          |
19| :---------------------------- | :--------------------- |
20| `PUT`    | `/sys/leases/lookup`          |
21
22### Parameters
23
24- `lease_id` `(string: <required>)` – Specifies the ID of the lease to lookup.
25
26### Sample Payload
27
28```json
29{
30  "lease_id": "aws/creds/deploy/abcd-1234..."
31}
32```
33
34### Sample Request
35
36```
37$ curl \
38    --header "X-Vault-Token: ..." \
39    --request PUT \
40    --data @payload.json \
41    http://127.0.0.1:8200/v1/sys/leases/lookup
42```
43
44### Sample Response
45
46```json
47{
48  "id": "auth/token/create/25c75065466dfc5f920525feafe47502c4c9915c",
49  "issue_time": "2017-04-30T10:18:11.228946471-04:00",
50  "expire_time": "2017-04-30T11:18:11.228946708-04:00",
51  "last_renewal_time": null,
52  "renewable": true,
53  "ttl": 3558
54}
55```
56
57## List Leases
58
59This endpoint returns a list of lease ids.
60
61**This endpoint requires 'sudo' capability.**
62
63| Method   | Path                         |
64| :--------------------------- | :--------------------- |
65| `LIST`   | `/sys/leases/lookup/:prefix` |
66
67
68### Sample Request
69
70```
71$ curl \
72    --header "X-Vault-Token: ..." \
73    --request LIST \
74    http://127.0.0.1:8200/v1/sys/leases/lookup/aws/creds/deploy/
75```
76
77### Sample Response
78
79```json
80{
81  "data":{
82    "keys":[
83      "abcd-1234...",
84      "efgh-1234...",
85      "ijkl-1234..."
86    ]
87  }
88}
89```
90
91## Renew Lease
92
93This endpoint renews a lease, requesting to extend the lease.
94
95| Method   | Path                          |
96| :---------------------------- | :--------------------- |
97| `PUT`    | `/sys/leases/renew`           |
98
99### Parameters
100
101- `lease_id` `(string: <required>)` – Specifies the ID of the lease to extend.
102  This can be specified as part of the URL or as part of the request body.
103
104- `increment` `(int: 0)` – Specifies the requested amount of time (in seconds)
105  to extend the lease.
106
107### Sample Payload
108
109```json
110{
111  "lease_id": "aws/creds/deploy/abcd-1234...",
112  "increment": 1800
113}
114```
115
116### Sample Request
117
118```
119$ curl \
120    --header "X-Vault-Token: ..." \
121    --request PUT \
122    --data @payload.json \
123    http://127.0.0.1:8200/v1/sys/leases/renew
124```
125
126### Sample Response
127
128```json
129{
130  "lease_id": "aws/creds/deploy/abcd-1234...",
131  "renewable": true,
132  "lease_duration": 2764790
133}
134```
135
136## Revoke Lease
137
138This endpoint revokes a lease immediately.
139
140| Method   | Path                          |
141| :---------------------------- | :--------------------- |
142| `PUT`    | `/sys/leases/revoke`          |
143
144### Parameters
145
146- `lease_id` `(string: <required>)` – Specifies the ID of the lease to revoke.
147
148### Sample Payload
149
150```json
151{
152  "lease_id": "postgresql/creds/readonly/abcd-1234..."
153}
154```
155
156### Sample Request
157
158```
159$ curl \
160    --header "X-Vault-Token: ..." \
161    --request PUT \
162    --data @payload.json \
163    http://127.0.0.1:8200/v1/sys/leases/revoke
164```
165
166## Revoke Force
167
168This endpoint revokes all secrets or tokens generated under a given prefix
169immediately. Unlike `/sys/leases/revoke-prefix`, this path ignores backend errors
170encountered during revocation. This is _potentially very dangerous_ and should
171only be used in specific emergency situations where errors in the backend or the
172connected backend service prevent normal revocation.
173
174By ignoring these errors, Vault abdicates responsibility for ensuring that the
175issued credentials or secrets are properly revoked and/or cleaned up. Access to
176this endpoint should be tightly controlled.
177
178**This endpoint requires 'sudo' capability.**
179
180| Method   | Path                                |
181| :---------------------------------- | :--------------------- |
182| `PUT`    | `/sys/leases/revoke-force/:prefix`  |
183
184### Parameters
185
186- `prefix` `(string: <required>)` – Specifies the prefix to revoke. This is
187  specified as part of the URL.
188
189### Sample Request
190
191```
192$ curl \
193    --header "X-Vault-Token: ..." \
194    --request PUT \
195    http://127.0.0.1:8200/v1/sys/leases/revoke-force/aws/creds
196```
197
198## Revoke Prefix
199
200This endpoint revokes all secrets (via a lease ID prefix) or tokens (via the
201tokens' path property) generated under a given prefix immediately. This requires
202`sudo` capability and access to it should be tightly controlled as it can be
203used to revoke very large numbers of secrets/tokens at once.
204
205**This endpoint requires 'sudo' capability.**
206
207| Method   | Path                                |
208| :---------------------------------- | :--------------------- |
209| `PUT`    | `/sys/leases/revoke-prefix/:prefix` |
210
211### Parameters
212
213- `prefix` `(string: <required>)` – Specifies the prefix to revoke. This is
214  specified as part of the URL.
215
216### Sample Request
217
218```
219$ curl \
220    --header "X-Vault-Token: ..." \
221    --request PUT \
222    http://127.0.0.1:8200/v1/sys/leases/revoke-prefix/aws/creds
223```
224