v1.14.5/website/content/api-docs/system/rekey.mdx - hashicorp/vault - Git at Google

 ---
 layout: api
 page_title: /sys/rekey - HTTP API
 description: The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
 ---

 # `/sys/rekey`

 @include 'alerts/restricted-root.mdx'

 The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.

 On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s)
 can be provided to rekey the root key since no unseal keys are available. The
 secret shares, secret threshold, and stored shares parameters must be set to 1.
 Upon successful rekey, no split unseal key shares are returned.

 ## Read rekey progress

 This endpoint reads the configuration and progress of the current rekey attempt.

 | Method | Path              |
 | :----- | :---------------- |
 | `GET`  | `/sys/rekey/init` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     http://127.0.0.1:8200/v1/sys/rekey/init
 ```

 ### Sample response

 ```json
 {
   "started": true,
   "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
   "t": 3,
   "n": 5,
   "progress": 1,
   "required": 3,
   "pgp_fingerprints": ["abcd1234"],
   "backup": true,
   "verification_required": false
 }
 ```

 If a rekey is started, then `n` is the new shares to generate and `t` is the
 threshold required for the new shares. `progress` is how many unseal keys have
 been provided for this rekey, where `required` must be reached to complete. The
 `nonce` for the current rekey operation is also displayed. If PGP keys are being
 used to encrypt the final shares, the key fingerprints and whether the final
 keys will be backed up to physical storage will also be displayed.
 `verification_required` indicates whether verification was enabled for this
 operation.

 ## Start rekey

 This endpoint initializes a new rekey attempt. Only a single rekey attempt can
 take place at a time, and changing the parameters of a rekey requires canceling
 and starting a new rekey, which will also provide a new nonce.

 | Method | Path              |
 | :----- | :---------------- |
 | `POST` | `/sys/rekey/init` |

 ### Parameters

 - `secret_shares` `(int: <required>)` – Specifies the number of shares to split
   the root key into.

 - `secret_threshold` `(int: <required>)` – Specifies the number of shares
   required to reconstruct the root key. This must be less than or equal to
   `secret_shares`.

 - `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used
   to encrypt the output unseal keys. Ordering is preserved. The keys must be
   base64-encoded from their original binary representation. The size of this
   array must be the same as `secret_shares`.

 - `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether
   Vault should also store a plaintext backup of the PGP-encrypted keys at
   `core/unseal-keys-backup` in the physical storage backend. These can then
   be retrieved and removed via the `sys/rekey/backup` endpoint.

 - `require_verification` `(bool: false)` – This turns on verification
   functionality. When verification is turned on, after successful authorization
   with the current unseal keys, the new unseal keys are returned but the master
   key is not actually rotated. The new keys must be provided to authorize the
   actual rotation of the root key. This ensures that the new keys have been
   successfully saved and protects against a risk of the keys being lost after
   rotation but before they can be persisted. This can be used with or without
   `pgp_keys`, and when used with it, it allows ensuring that the returned keys
   can be successfully decrypted before committing to the new shares, which the
   backup functionality does not provide.

 ### Sample payload

 ```json
 {
   "secret_shares": 10,
   "secret_threshold": 5
 }
 ```

 ### Sample request

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

 ## Cancel rekey

 This endpoint cancels any in-progress rekey. This clears the rekey settings as
 well as any progress made. This must be called to change the parameters of the
 rekey. Note: verification is still a part of a rekey. If rekeying is canceled
 during the verification flow, the current unseal keys remain valid.

 | Method   | Path              |
 | :------- | :---------------- |
 | `DELETE` | `/sys/rekey/init` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     --request DELETE \
     http://127.0.0.1:8200/v1/sys/rekey/init
 ```

 ## Read backup key

 This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned
 value is the nonce of the rekey operation and a map of PGP key fingerprint to
 hex-encoded PGP-encrypted key.

 | Method | Path                |
 | :----- | :------------------ |
 | `GET`  | `/sys/rekey/backup` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     http://127.0.0.1:8200/v1/sys/rekey/backup
 ```

 ### Sample response

 ```json
 {
   "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
   "keys": {
     "abcd1234": "..."
   }
 }
 ```

 ## Delete backup key

 This endpoint deletes the backup copy of PGP-encrypted unseal keys.

 | Method   | Path                |
 | :------- | :------------------ |
 | `DELETE` | `/sys/rekey/backup` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     --request DELETE \
     http://127.0.0.1:8200/v1/sys/rekey/backup
 ```

 ## Submit key

 This endpoint is used to enter a single root key share to progress the rekey
 of the Vault. If the threshold number of root key shares is reached, Vault
 will complete the rekey. Otherwise, this API must be called multiple times until
 that threshold is met. The rekey nonce operation must be provided with each
 call.

 When the operation is complete, this will return a response like the example
 below; otherwise the response will be the same as the `GET` method against
 `sys/rekey/init`, providing status on the operation itself.

 If verification was requested, successfully completing this flow will
 immediately put the operation into a verification state, and provide the nonce
 for the verification operation.

 | Method | Path                |
 | :----- | :------------------ |
 | `POST` | `/sys/rekey/update` |

 ### Parameters

 - `key` `(string: <required>)` – Specifies a single master share key.

 - `nonce` `(string: <required>)` – Specifies the nonce of the rekey operation.

 ### Sample payload

 ```json
 {
   "key": "AB32...",
   "nonce": "abcd1234..."
 }
 ```

 ### Sample request

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

 ### Sample response

 ```json
 {
   "complete": true,
   "keys": ["one", "two", "three"],
   "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
   "pgp_fingerprints": ["abcd1234"],
   "keys_base64": ["base64keyvalue"],
   "backup": true,
   "verification_required": true,
   "verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10"
 }
 ```

 If the keys are PGP-encrypted, an array of key fingerprints will also be
 provided (with the order in which the keys were used for encryption) along with
 whether or not the keys were backed up to physical storage.

 ## Read rekey verification progress

 This endpoint reads the configuration and progress of the current rekey
 verification attempt.

 | Method | Path                |
 | :----- | :------------------ |
 | `GET`  | `/sys/rekey/verify` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     http://127.0.0.1:8200/v1/sys/rekey/verify
 ```

 ### Sample response

 ```json
 {
   "nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10",
   "t": 3,
   "n": 5,
   "progress": 1
 }
 ```

 `n` is the total number of new shares that were generated and `t` is the
 threshold required for the new shares to pass verification. `progress` is how
 many of the new unseal keys have been provided for this verification operation.
 The `nonce` for the current rekey operation is also displayed.

 ## Cancel rekey verification

 This endpoint cancels any in-progress rekey verification operation. This clears
 any progress made and resets the nonce. Unlike a `DELETE` against
 `sys/rekey/init`, this only resets the current verification operation, not the
 entire rekey attempt. The return value is the same as `GET` along with the new
 nonce.

 | Method   | Path                |
 | :------- | :------------------ |
 | `DELETE` | `/sys/rekey/verify` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     --request DELETE \
     http://127.0.0.1:8200/v1/sys/rekey/verify
 ```

 ### Sample response

 ```json
 {
   "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
   "t": 3,
   "n": 5,
   "progress": 0
 }
 ```

 ## Submit verification key

 This endpoint is used to enter a single new key share to progress the rekey
 verification operation. If the threshold number of new key shares is reached,
 Vault will complete the rekey by performing the actual rotation of the master
 key. Otherwise, this API must be called multiple times until that threshold is
 met. The nonce must be provided with each call.

 When the operation is complete, this will return a response like the example
 below; otherwise the response will be the same as the `GET` method against
 `sys/rekey/verify`, providing status on the operation itself.

 | Method | Path                |
 | :----- | :------------------ |
 | `POST` | `/sys/rekey/verify` |

 ### Parameters

 - `key` `(string: <required>)` – Specifies a single master share key from the
   new set of shares.

 - `nonce` `(string: <required>)` – Specifies the nonce of the rekey
   verification operation.

 ### Sample payload

 ```json
 {
   "key": "A58d...",
   "nonce": "5a27bbc1..."
 }
 ```

 ### Sample request

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

 ### Sample response

 ```json
 {
   "nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
   "complete": true
 }
 ```
	---
	layout: api
	page_title: /sys/rekey - HTTP API
	description: The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.
	---

	# `/sys/rekey`

	@include 'alerts/restricted-root.mdx'

	The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault.

	On seals that support stored keys (e.g. HSM PKCS11), the recovery key share(s)
	can be provided to rekey the root key since no unseal keys are available. The
	secret shares, secret threshold, and stored shares parameters must be set to 1.
	Upon successful rekey, no split unseal key shares are returned.

	## Read rekey progress

	This endpoint reads the configuration and progress of the current rekey attempt.

	\| Method \| Path \|
	\| :----- \| :---------------- \|
	\| `GET` \| `/sys/rekey/init` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	http://127.0.0.1:8200/v1/sys/rekey/init
	```

	### Sample response

	```json
	{
	"started": true,
	"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
	"t": 3,
	"n": 5,
	"progress": 1,
	"required": 3,
	"pgp_fingerprints": ["abcd1234"],
	"backup": true,
	"verification_required": false
	}
	```

	If a rekey is started, then `n` is the new shares to generate and `t` is the
	threshold required for the new shares. `progress` is how many unseal keys have
	been provided for this rekey, where `required` must be reached to complete. The
	`nonce` for the current rekey operation is also displayed. If PGP keys are being
	used to encrypt the final shares, the key fingerprints and whether the final
	keys will be backed up to physical storage will also be displayed.
	`verification_required` indicates whether verification was enabled for this
	operation.

	## Start rekey

	This endpoint initializes a new rekey attempt. Only a single rekey attempt can
	take place at a time, and changing the parameters of a rekey requires canceling
	and starting a new rekey, which will also provide a new nonce.

	\| Method \| Path \|
	\| :----- \| :---------------- \|
	\| `POST` \| `/sys/rekey/init` \|

	### Parameters

	- `secret_shares` `(int: <required>)` – Specifies the number of shares to split
	the root key into.

	- `secret_threshold` `(int: <required>)` – Specifies the number of shares
	required to reconstruct the root key. This must be less than or equal to
	`secret_shares`.

	- `pgp_keys` `(array<string>: nil)` – Specifies an array of PGP public keys used
	to encrypt the output unseal keys. Ordering is preserved. The keys must be
	base64-encoded from their original binary representation. The size of this
	array must be the same as `secret_shares`.

	- `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether
	Vault should also store a plaintext backup of the PGP-encrypted keys at
	`core/unseal-keys-backup` in the physical storage backend. These can then
	be retrieved and removed via the `sys/rekey/backup` endpoint.

	- `require_verification` `(bool: false)` – This turns on verification
	functionality. When verification is turned on, after successful authorization
	with the current unseal keys, the new unseal keys are returned but the master
	key is not actually rotated. The new keys must be provided to authorize the
	actual rotation of the root key. This ensures that the new keys have been
	successfully saved and protects against a risk of the keys being lost after
	rotation but before they can be persisted. This can be used with or without
	`pgp_keys`, and when used with it, it allows ensuring that the returned keys
	can be successfully decrypted before committing to the new shares, which the
	backup functionality does not provide.

	### Sample payload

	```json
	{
	"secret_shares": 10,
	"secret_threshold": 5
	}
	```

	### Sample request

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

	## Cancel rekey

	This endpoint cancels any in-progress rekey. This clears the rekey settings as
	well as any progress made. This must be called to change the parameters of the
	rekey. Note: verification is still a part of a rekey. If rekeying is canceled
	during the verification flow, the current unseal keys remain valid.

	\| Method \| Path \|
	\| :------- \| :---------------- \|
	\| `DELETE` \| `/sys/rekey/init` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	--request DELETE \
	http://127.0.0.1:8200/v1/sys/rekey/init
	```

	## Read backup key

	This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned
	value is the nonce of the rekey operation and a map of PGP key fingerprint to
	hex-encoded PGP-encrypted key.

	\| Method \| Path \|
	\| :----- \| :------------------ \|
	\| `GET` \| `/sys/rekey/backup` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	http://127.0.0.1:8200/v1/sys/rekey/backup
	```

	### Sample response

	```json
	{
	"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
	"keys": {
	"abcd1234": "..."
	}
	}
	```

	## Delete backup key

	This endpoint deletes the backup copy of PGP-encrypted unseal keys.

	\| Method \| Path \|
	\| :------- \| :------------------ \|
	\| `DELETE` \| `/sys/rekey/backup` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	--request DELETE \
	http://127.0.0.1:8200/v1/sys/rekey/backup
	```

	## Submit key

	This endpoint is used to enter a single root key share to progress the rekey
	of the Vault. If the threshold number of root key shares is reached, Vault
	will complete the rekey. Otherwise, this API must be called multiple times until
	that threshold is met. The rekey nonce operation must be provided with each
	call.

	When the operation is complete, this will return a response like the example
	below; otherwise the response will be the same as the `GET` method against
	`sys/rekey/init`, providing status on the operation itself.

	If verification was requested, successfully completing this flow will
	immediately put the operation into a verification state, and provide the nonce
	for the verification operation.

	\| Method \| Path \|
	\| :----- \| :------------------ \|
	\| `POST` \| `/sys/rekey/update` \|

	### Parameters

	- `key` `(string: <required>)` – Specifies a single master share key.

	- `nonce` `(string: <required>)` – Specifies the nonce of the rekey operation.

	### Sample payload

	```json
	{
	"key": "AB32...",
	"nonce": "abcd1234..."
	}
	```

	### Sample request

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

	### Sample response

	```json
	{
	"complete": true,
	"keys": ["one", "two", "three"],
	"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
	"pgp_fingerprints": ["abcd1234"],
	"keys_base64": ["base64keyvalue"],
	"backup": true,
	"verification_required": true,
	"verification_nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10"
	}
	```

	If the keys are PGP-encrypted, an array of key fingerprints will also be
	provided (with the order in which the keys were used for encryption) along with
	whether or not the keys were backed up to physical storage.

	## Read rekey verification progress

	This endpoint reads the configuration and progress of the current rekey
	verification attempt.

	\| Method \| Path \|
	\| :----- \| :------------------ \|
	\| `GET` \| `/sys/rekey/verify` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	http://127.0.0.1:8200/v1/sys/rekey/verify
	```

	### Sample response

	```json
	{
	"nonce": "8b112c9e-2738-929d-bcc2-19aff249ff10",
	"t": 3,
	"n": 5,
	"progress": 1
	}
	```

	`n` is the total number of new shares that were generated and `t` is the
	threshold required for the new shares to pass verification. `progress` is how
	many of the new unseal keys have been provided for this verification operation.
	The `nonce` for the current rekey operation is also displayed.

	## Cancel rekey verification

	This endpoint cancels any in-progress rekey verification operation. This clears
	any progress made and resets the nonce. Unlike a `DELETE` against
	`sys/rekey/init`, this only resets the current verification operation, not the
	entire rekey attempt. The return value is the same as `GET` along with the new
	nonce.

	\| Method \| Path \|
	\| :------- \| :------------------ \|
	\| `DELETE` \| `/sys/rekey/verify` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	--request DELETE \
	http://127.0.0.1:8200/v1/sys/rekey/verify
	```

	### Sample response

	```json
	{
	"nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
	"t": 3,
	"n": 5,
	"progress": 0
	}
	```

	## Submit verification key

	This endpoint is used to enter a single new key share to progress the rekey
	verification operation. If the threshold number of new key shares is reached,
	Vault will complete the rekey by performing the actual rotation of the master
	key. Otherwise, this API must be called multiple times until that threshold is
	met. The nonce must be provided with each call.

	When the operation is complete, this will return a response like the example
	below; otherwise the response will be the same as the `GET` method against
	`sys/rekey/verify`, providing status on the operation itself.

	\| Method \| Path \|
	\| :----- \| :------------------ \|
	\| `POST` \| `/sys/rekey/verify` \|

	### Parameters

	- `key` `(string: <required>)` – Specifies a single master share key from the
	new set of shares.

	- `nonce` `(string: <required>)` – Specifies the nonce of the rekey
	verification operation.

	### Sample payload

	```json
	{
	"key": "A58d...",
	"nonce": "5a27bbc1..."
	}
	```

	### Sample request

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

	### Sample response

	```json
	{
	"nonce": "5827bbc1-0110-5725-cc21-beddc129d942",
	"complete": true
	}
	```