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