1---
2layout: "api"
3page_title: "/sys/generate-root - HTTP API"
4sidebar_title: "<code>/sys/generate-root</code>"
5sidebar_current: "api-http-system-generate-root"
6description: |-
7  The `/sys/generate-root/` endpoints are used to create a new root key for
8  Vault.
9---
10
11# `/sys/generate-root`
12
13The `/sys/generate-root` endpoint is used to create a new root key for Vault.
14
15## Read Root Generation Progress
16
17This endpoint reads the configuration and process of the current root generation
18attempt.
19
20| Method   | Path                         |
21| :--------------------------- | :--------------------- |
22| `GET`    | `/sys/generate-root/attempt` |
23
24### Sample Request
25
26```
27$ curl \
28    http://127.0.0.1:8200/v1/sys/generate-root/attempt
29```
30
31### Sample Response
32
33```json
34{
35  "started": true,
36  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
37  "progress": 1,
38  "required": 3,
39  "encoded_token": "",
40  "pgp_fingerprint": "",
41  "complete": false
42}
43```
44
45If a root generation is started, `progress` is how many unseal keys have been
46provided for this generation attempt, where `required` must be reached to
47complete. The `nonce` for the current attempt and whether the attempt is
48complete is also displayed. If a PGP key is being used to encrypt the final root
49token, its fingerprint will be returned. Note that if an OTP is being used to
50encode the final root token, it will never be returned.
51
52## Start Root Token Generation
53
54This endpoint initializes a new root generation attempt. Only a single root
55generation attempt can take place at a time.
56
57| Method   | Path                         |
58| :--------------------------- | :--------------------- |
59| `PUT`    | `/sys/generate-root/attempt` |
60
61### Parameters
62
63- `pgp_key` `(string: <optional>)` – Specifies a base64-encoded PGP public key.
64  The raw bytes of the token will be encrypted with this value before being
65  returned to the final unseal key provider.
66
67### Sample Request
68
69```
70$ curl \
71    --request PUT \
72    http://127.0.0.1:8200/v1/sys/generate-root/attempt
73```
74
75### Sample Response
76
77```json
78{
79  "started": true,
80  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
81  "progress": 1,
82  "required": 3,
83  "encoded_token": "",
84  "otp": "2vPFYG8gUSW9npwzyvxXMug0",
85  "otp_length" :24,
86  "complete": false
87}
88```
89
90## Cancel Root Generation
91
92This endpoint cancels any in-progress root generation attempt. This clears any
93progress made. This must be called to change the OTP or PGP key being used.
94
95| Method   | Path                         |
96| :--------------------------- | :--------------------- |
97| `DELETE` | `/sys/generate-root/attempt` |
98
99### Sample Request
100
101```
102$ curl \
103    --request DELETE \
104    http://127.0.0.1:8200/v1/sys/generate-root/attempt
105```
106
107## Provide Key Share to Generate Root
108
109This endpoint is used to enter a single master key share to progress the root
110generation attempt. If the threshold number of master key shares is reached,
111Vault will complete the root generation and issue the new token.  Otherwise,
112this API must be called multiple times until that threshold is met. The attempt
113nonce must be provided with each call.
114
115| Method   | Path                         |
116| :--------------------------- | :--------------------- |
117| `PUT`    | `/sys/generate-root/update`  |
118
119### Parameters
120
121- `key` `(string: <required>)` – Specifies a single master key share.
122
123- `nonce` `(string: <required>)` – Specifies the nonce of the attempt.
124
125### Sample Payload
126
127```json
128{
129  "key": "acbd1234",
130  "nonce": "ad235"
131}
132```
133
134### Sample Request
135
136```
137$ curl \
138    --request PUT \
139    --data @payload.json \
140    http://127.0.0.1:8200/v1/sys/generate-root/update
141```
142
143### Sample Response
144
145This returns a JSON-encoded object indicating the attempt nonce, and completion
146status, and the encoded root token, if the attempt is complete.
147
148```json
149{
150  "started": true,
151  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
152  "progress": 3,
153  "required": 3,
154  "pgp_fingerprint": "",
155  "complete": true,
156  "encoded_token": "FPzkNBvwNDeFh4SmGA8c+w=="
157}
158```
159