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