1---
2layout: "api"
3page_title: "/sys/rekey - HTTP API"
4sidebar_title: "<code>/sys/rekey</code>"
5sidebar_current: "api-http-system-rekey"
6description: |-
7  The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
8---
9
10# `/sys/rekey`
11
12The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
13
14On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s)
15can be provided to rekey the master key since no unseal keys are available. The
16secret shares, secret threshold, and stored shares parameters must be set to 1.
17Upon successful rekey, no split unseal key shares are returned.
18
19## Read Rekey Progress
20
21This endpoint reads the configuration and progress of the current rekey attempt.
22
23| Method   | Path                         |
24| :--------------------------- | :--------------------- |
25| `GET`    | `/sys/rekey/init`            |
26
27### Sample Request
28
29```
30$ curl \
31    --header "X-Vault-Token: ..." \
32    http://127.0.0.1:8200/v1/sys/rekey/init
33```
34
35### Sample Response
36
37```json
38{
39  "started": true,
40  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
41  "t": 3,
42  "n": 5,
43  "progress": 1,
44  "required": 3,
45  "pgp_fingerprints": ["abcd1234"],
46  "backup": true,
47  "verification_required": false
48}
49```
50
51If a rekey is started, then `n` is the new shares to generate and `t` is the
52threshold required for the new shares. `progress` is how many unseal keys have
53been provided for this rekey, where `required` must be reached to complete. The
54`nonce` for the current rekey operation is also displayed. If PGP keys are being
55used to encrypt the final shares, the key fingerprints and whether the final
56keys will be backed up to physical storage will also be displayed.
57`verification_required` indicates whether verification was enabled for this
58operation.
59
60## Start Rekey
61
62This endpoint initializes a new rekey attempt. Only a single rekey attempt can
63take place at a time, and changing the parameters of a rekey requires canceling
64and starting a new rekey, which will also provide a new nonce.
65
66| Method   | Path                         |
67| :--------------------------- | :--------------------- |
68| `PUT`    | `/sys/rekey/init`            |
69
70### Parameters
71
72- `secret_shares` `(int: <required>)` – Specifies the number of shares to split
73  the master key into.
74
75- `secret_threshold` `(int: <required>)` – Specifies the number of shares
76  required to reconstruct the master key. This must be less than or equal to
77  `secret_shares`.
78
79- `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used
80  to encrypt the output unseal keys. Ordering is preserved. The keys must be
81  base64-encoded from their original binary representation. The size of this
82  array must be the same as `secret_shares`.
83
84- `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether
85  Vault should also store a plaintext backup of the PGP-encrypted keys at
86  `core/unseal-keys-backup` in the physical storage backend. These can then
87  be retrieved and removed via the `sys/rekey/backup` endpoint.
88
89- `require_verification` `(bool: false)` – This turns on verification
90  functionality. When verification is turned on, after successful authorization
91  with the current unseal keys, the new unseal keys are returned but the master
92  key is not actually rotated. The new keys must be provided to authorize the
93  actual rotation of the master key. This ensures that the new keys have been
94  successfully saved and protects against a risk of the keys being lost after
95  rotation but before they can be persisted. This can be used with without
96  `pgp_keys`, and when used with it, it allows ensuring that the returned keys
97  can be successfully decrypted before committing to the new shares, which the
98  backup functionality does not provide.
99
100### Sample Payload
101
102```json
103{
104  "secret_shares": 10,
105  "secret_threshold": 5
106}
107```
108
109### Sample Request
110
111```
112$ curl \
113    --header "X-Vault-Token: ..." \
114    --request PUT \
115    --data @payload.json \
116    http://127.0.0.1:8200/v1/sys/rekey/init
117```
118
119## Cancel Rekey
120
121This endpoint cancels any in-progress rekey. This clears the rekey settings as
122well as any progress made. This must be called to change the parameters of the
123rekey. Note: verification is still a part of a rekey. If rekeying is canceled
124during the verification flow, the current unseal keys remain valid.
125
126| Method   | Path                         |
127| :--------------------------- | :--------------------- |
128| `DELETE` | `/sys/rekey/init`            |
129
130### Sample Request
131
132```
133$ curl \
134    --header "X-Vault-Token: ..." \
135    --request DELETE \
136    http://127.0.0.1:8200/v1/sys/rekey/init
137```
138
139## Read Backup Key
140
141This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned
142value is the nonce of the rekey operation and a map of PGP key fingerprint to
143hex-encoded PGP-encrypted key.
144
145| Method   | Path                         |
146| :--------------------------- | :--------------------- |
147| `GET`    | `/sys/rekey/backup`          |
148
149### Sample Request
150
151```
152$ curl \
153    --header "X-Vault-Token: ..." \
154    http://127.0.0.1:8200/v1/sys/rekey/backup
155```
156
157### Sample Response
158
159```json
160{
161  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
162  "keys": {
163    "abcd1234": "..."
164  }
165}
166```
167
168## Delete Backup Key
169
170This endpoint deletes the backup copy of PGP-encrypted unseal keys.
171
172| Method   | Path                         |
173| :--------------------------- | :--------------------- |
174| `DELETE` | `/sys/rekey/backup`          |
175
176### Sample Request
177
178```
179$ curl \
180    --header "X-Vault-Token" \
181    --request DELETE \
182    http://127.0.0.1:8200/v1/sys/rekey/backup
183```
184
185## Submit Key
186
187This endpoint is used to enter a single master key share to progress the rekey
188of the Vault. If the threshold number of master key shares is reached, Vault
189will complete the rekey. Otherwise, this API must be called multiple times until
190that threshold is met. The rekey nonce operation must be provided with each
191call.
192
193When the operation is complete, this will return a response like the example
194below; otherwise the response will be the same as the `GET` method against
195`sys/rekey/init`, providing status on the operation itself.
196
197If verification was requested, successfully completing this flow will
198immediately put the operation into a verification state, and provide the nonce
199for the verification operation.
200
201| Method   | Path                         |
202| :--------------------------- | :--------------------- |
203| `PUT`    | `/sys/rekey/update`          |
204
205### Parameters
206
207- `key` `(string: <required>)` – Specifies a single master share key.
208
209- `nonce` `(string: <required>)` – Specifies the nonce of the rekey operation.
210
211### Sample Payload
212
213```json
214{
215  "key": "AB32...",
216  "nonce": "abcd1234..."
217}
218```
219
220### Sample Request
221
222```
223$ curl \
224    --header "X-Vault-Token" \
225    --request PUT \
226    --data @payload.json \
227    http://127.0.0.1:8200/v1/sys/rekey/update
228```
229
230### Sample Response
231
232```json
233{
234  "complete": true,
235  "keys": ["one", "two", "three"],
236  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
237  "pgp_fingerprints": ["abcd1234"],
238  "keys_base64": ["base64keyvalue"],
239  "backup": true,
240  "verification_required": true,
241  "verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10"
242}
243```
244
245If the keys are PGP-encrypted, an array of key fingerprints will also be
246provided (with the order in which the keys were used for encryption) along with
247whether or not the keys were backed up to physical storage.
248
249## Read Rekey Verification Progress
250
251This endpoint reads the configuration and progress of the current rekey
252verification attempt.
253
254| Method   | Path                           |
255| :----------------------------- | :--------------------- |
256| `GET`    | `/sys/rekey/verify`            |
257
258### Sample Request
259
260```
261$ curl \
262    --header "X-Vault-Token: ..." \
263    http://127.0.0.1:8200/v1/sys/rekey/verify
264```
265
266### Sample Response
267
268```json
269{
270  "nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10",
271  "t": 3,
272  "n": 5,
273  "progress": 1
274}
275```
276
277`n` is the total number of new shares that were generated and `t` is the
278threshold required for the new shares to pass verification. `progress` is how
279many of the new unseal keys have been provided for this verification operation.
280The `nonce` for the current rekey operation is also displayed.
281
282## Cancel Rekey Verification
283
284This endpoint cancels any in-progress rekey verification operation. This clears
285any progress made and resets the nonce. Unlike a `DELETE` against
286`sys/rekey/init`, this only resets the current verification operation, not the
287entire rekey atttempt. The return value is the same as `GET` along with the new
288nonce.
289
290| Method   | Path                           |
291| :----------------------------- | :--------------------- |
292| `DELETE` | `/sys/rekey/verify`            | `200 (empty body)`     |
293
294### Sample Request
295
296```
297$ curl \
298    --header "X-Vault-Token" \
299    --request DELETE \
300    http://127.0.0.1:8200/v1/sys/rekey/verify
301```
302
303### Sample Response
304
305```json
306{
307  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
308  "t": 3,
309  "n": 5,
310  "progress": 0
311}
312```
313
314## Submit Verification Key
315
316This endpoint is used to enter a single new key share to progress the rekey
317verification operation.  If the threshold number of new key shares is reached,
318Vault will complete the rekey by performing the actual rotation of the master
319key. Otherwise, this API must be called multiple times until that threshold is
320met. The nonce must be provided with each call.
321
322When the operation is complete, this will return a response like the example
323below; otherwise the response will be the same as the `GET` method against
324`sys/rekey/verify`, providing status on the operation itself.
325
326| Method   | Path                         |
327| :--------------------------- | :--------------------- |
328| `PUT`    | `/sys/rekey/verify`          |
329
330### Parameters
331
332- `key` `(string: <required>)` – Specifies a single master share key from the
333  new set of shares.
334
335- `nonce` `(string: <required>)` – Specifies the nonce of the rekey
336  verification operation.
337
338### Sample Payload
339
340```json
341{
342  "key": "A58d...",
343  "nonce": "5a27bbc1..."
344}
345```
346
347### Sample Request
348
349```
350$ curl \
351    --header "X-Vault-Token" \
352    --request PUT \
353    --data @payload.json \
354    http://127.0.0.1:8200/v1/sys/rekey/verify
355```
356
357### Sample Response
358
359```json
360{
361  "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
362  "complete": true
363}
364```
365