open-vault/website/source/docs/http/sys-generate-root.html.md

layout	page_title	sidebar_current	description
http	HTTP API: /sys/generate-root/	docs-http-sys-generate-root	The `/sys/generate-root/` endpoints are used to create a new root key for Vault.

/sys/generate-root/attempt

GET

Description

Reads the configuration and progress of the current root generation attempt.

Method

GET

URL

`/sys/generate-root/attempt`

Parameters

None

Returns

If a root generation is started, `progress` is how many unseal keys have been provided for this generation attempt, where `required` must be reached to complete. The `nonce` for the current attempt and whether the attempt is complete is also displayed. If a PGP key is being used to encrypt the final root token, its fingerprint will be returned. Note that if an OTP is being used to encode the final root token, it will never be returned.

```javascript
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "pgp_fingerprint": "",
  "complete": false
}
```

PUT

Description

Initializes a new root generation attempt. Only a single root generation attempt can take place at a time. One (and only one) of `otp` or `pgp_key` are required.

Method

PUT

URL

`/sys/generate-root/attempt`

Parameters

• otp optional A base64-encoded 16-byte value. The raw bytes of the token will be XOR'd with this value before being returned to the final unseal key provider.
• pgp_key optional A base64-encoded PGP public key. The raw bytes of the token will be encrypted with this value before being returned to the final unseal key provider.

Returns

The current progress.

```javascript
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793",
  "complete": false
}
```

DELETE

Description

Cancels any in-progress root generation attempt. This clears any progress made. This must be called to change the OTP or PGP key being used.

Method

DELETE

URL

`/sys/generate-root/attempt`

Parameters

None

Returns

`204` response code.

/sys/generate-root/update

PUT

Description

Enter a single master key share to progress the root generation attempt. If the threshold number of master key shares is reached, Vault will complete the root generation and issue the new token. Otherwise, this API must be called multiple times until that threshold is met. The attempt nonce must be provided with each call.

Method

PUT

URL

`/sys/generate-root/update`

Parameters

• key required A single master share key.
• nonce required The nonce of the attempt.

Returns

A JSON-encoded object indicating the attempt nonce, and completion status, and the encoded root token, if the attempt is complete.

```javascript
{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 3,
  "required": 3,
  "pgp_fingerprint": "",
  "complete": true,
  "encoded_root_token": "FPzkNBvwNDeFh4SmGA8c+w=="
}
```