Skip to main content

/sys/generate-recovery-token

The /sys/generate-recovery-token endpoint is used to create a new recovery token for OpenBao.

Read recovery token generation progress​

This endpoint reads the configuration and process of the current root generation attempt.

MethodPath
GET/sys/generate-recovery-token/attempt

Sample request​

$ curl \
    http://127.0.0.1:8200/v1/sys/generate-recovery-token/attempt

Sample response​

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

If a recovery token 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.

If an OTP is being used to encode the final root token it will be returned only once, on the response to the start request.

The OTP is a base62 string, with length of otp_length. The raw bytes (char codes) of the token will be XOR'd with this value before being returned as a response to the final unseal key, encoded as base64.

Start recovery token generation​

This endpoint initializes a new recovery token generation attempt. Only a single recovery token generation attempt can take place at a time.

MethodPath
POST/sys/generate-recovery-token/attempt

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 POST \
    http://127.0.0.1:8200/v1/sys/generate-recovery-token/attempt

Sample response​

{
  "started": true,
  "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63",
  "progress": 1,
  "required": 3,
  "encoded_token": "",
  "otp": "2vPFYG8gUSW9npwzyvxXMug0",
  "otp_length": 24,
  "complete": false
}

Cancel recovery token generation​

This endpoint cancels any in-progress recovery token generation attempt. This clears any progress made. This must be called to change the OTP or PGP key being used.

MethodPath
DELETE/sys/generate-recovery-token/attempt

Sample request​

$ curl \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/generate-recovery-token/attempt

Provide key share to generate recovery token​

This endpoint is used to enter a single root key share to progress the recovery token generation attempt. If the threshold number of root key shares is reached, OpenBao will complete the recovery token 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.

Note that once a token has been issued, OpenBao is unsealed. The token lives only in memory and thus will only be valid until the next restart.

MethodPath
POST/sys/generate-recovery-token/update

Parameters​

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

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

Sample payload​

{
  "key": "acbd1234",
  "nonce": "ad235"
}

Sample request​

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/generate-recovery-token/update

Sample response​

This returns a JSON-encoded object indicating the attempt nonce, and completion status, and the encoded recovery token, if the attempt is complete.

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