open-vault/website/source/api/system/rekey-recovery-key.html.md

layout	page_title	sidebar_current	description
api	/sys/rekey-recovery-key - HTTP API	docs-http-system-rekey-recovery-key	The `/sys/rekey-recovery-key` endpoints are used to rekey the recovery keys for Vault.

/sys/rekey-recovery-key

~> Note: These endpoints are only applicable to seals that support recovery keys.

The /sys/rekey-recovery-key endpoints are used to rekey the recovery keys for Vault.

Read Rekey Progress

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

Method	Path	Produces
GET	/sys/rekey-recovery-key/init	200 application/json

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/sys/rekey-recovery-key/init

Sample Response

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

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 recovery 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.

Start Rekey

This endpoint initializes a new rekey attempt. Only a single recovery key 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	Produces
PUT	/sys/rekey-recovery-key/init	204 (empty body)

Parameters

• secret_shares (int: <required>) – Specifies the number of shares to split the recovery key into.

• secret_threshold (int: <required>) – Specifies the number of shares required to reconstruct the recovery 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 recovery key shares. 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/recovery-keys-backup in the physical storage backend. These can then be retrieved and removed via the sys/rekey-recovery-key/backup endpoint.

Sample Payload

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

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request PUT \
    --data @payload.json \
    https://vault.rocks/v1/sys/rekey-recovery-key/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.

Method	Path	Produces
DELETE	/sys/rekey-recovery-key/init	204 (empty body)

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault.rocks/v1/sys/rekey-recovery-key/init

Read Backup Key

This endpoint returns the backup copy of PGP-encrypted recovery key shares. 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	Produces
GET	/sys/rekey-recovery-key/backup	200 application/json

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/sys/rekey-recovery-key/backup

Sample Response

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

Delete Backup Key

This endpoint deletes the backup copy of PGP-encrypted recovery key shares.

Method	Path	Produces
DELETE	/sys/rekey-recovery-key/backup	204 (empty body)

Sample Request

$ curl \
    --header "X-Vault-Token" \
    --request DELETE \
    https://vault.rocks/v1/sys/rekey-recovery-key/backup

Submit Key

This endpoint is used to enter a single recovery key share to progress the rekey of the Vault. If the threshold number of recovery 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.

Method	Path	Produces
PUT	/sys/rekey-recovery-key/update	200 application/json

Parameters

• key (string: <required>) – Specifies a single recovery share key.

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

Sample Payload

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

Sample Request

$ curl \
    --header "X-Vault-Token" \
    --request PUT \
    --data @payload.json \
    https://vault.rocks/v1/sys/rekey-recovery-key/update

Sample Response

{
  "complete": true,
  "keys": ["one", "two", "three"],
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "pgp_fingerprints": ["abcd1234"],
  "keys_base64": ["base64keyvalue"],
  "backup": true
}

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.