mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-20 22:21:09 +02:00
a43e292424
* conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
159 lines
4.1 KiB
Markdown
159 lines
4.1 KiB
Markdown
---
|
||
layout: "api"
|
||
page_title: "/sys/generate-root - HTTP API"
|
||
sidebar_title: "<tt>/sys/generate-root</tt>"
|
||
sidebar_current: "api-http-system-generate-root"
|
||
description: |-
|
||
The `/sys/generate-root/` endpoints are used to create a new root key for
|
||
Vault.
|
||
---
|
||
|
||
# `/sys/generate-root`
|
||
|
||
The `/sys/generate-root` endpoint is used to create a new root key for Vault.
|
||
|
||
## Read Root Generation Progress
|
||
|
||
This endpoint reads the configuration and process of the current root generation
|
||
attempt.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `GET` | `/sys/generate-root/attempt` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
http://127.0.0.1:8200/v1/sys/generate-root/attempt
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"started": true,
|
||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||
"progress": 1,
|
||
"required": 3,
|
||
"encoded_token": "",
|
||
"pgp_fingerprint": "",
|
||
"complete": false
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
## Start Root Token Generation
|
||
|
||
This endpoint initializes a new root generation attempt. Only a single root
|
||
generation attempt can take place at a time.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `PUT` | `/sys/generate-root/attempt` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `pgp_key` `(string: <optional>)` – Specifies 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.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--request PUT \
|
||
http://127.0.0.1:8200/v1/sys/generate-root/attempt
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"started": true,
|
||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||
"progress": 1,
|
||
"required": 3,
|
||
"encoded_token": "",
|
||
"otp": "2vPFYG8gUSW9npwzyvxXMug0",
|
||
"otp_length" :24,
|
||
"complete": false
|
||
}
|
||
```
|
||
|
||
## Cancel Root Generation
|
||
|
||
This endpoint 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 | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `DELETE` | `/sys/generate-root/attempt` | `204 (empty body)` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/sys/generate-root/attempt
|
||
```
|
||
|
||
## Provide Key Share to Generate Root
|
||
|
||
This endpoint is used to 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 | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `PUT` | `/sys/generate-root/update` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `key` `(string: <required>)` – Specifies a single master key share.
|
||
|
||
- `nonce` `(string: <required>)` – Specifies the nonce of the attempt.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"key": "acbd1234",
|
||
"nonce": "ad235"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--request PUT \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/generate-root/update
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
This returns a JSON-encoded object indicating the attempt nonce, and completion
|
||
status, and the encoded root token, if the attempt is complete.
|
||
|
||
```json
|
||
{
|
||
"started": true,
|
||
"nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
|
||
"progress": 3,
|
||
"required": 3,
|
||
"pgp_fingerprint": "",
|
||
"complete": true,
|
||
"encoded_token": "FPzkNBvwNDeFh4SmGA8c+w=="
|
||
}
|
||
```
|