/sys/init

The /sys/init endpoint is used to initialize a new OpenBao instance. When using an auto-unseal mechanism, it is possible to initialize OpenBao (since v2.4.0) with recovery_shares config parameter set as 0, resulting in the recovery keys not being generated at initialization time, and thus will not be returned back to the operator. The system will function as if it has no recovery keys. To create recovery keys the operator is required to to manually call init endpoint, which will return working keys immediately. This is not applicable for Shamir's based unsealing. Recovery mode will not function until such keys are created, and the operator will be unable to use the API to unseal a manually sealed auto-unseal instance. Only restarting an instance will allow a manually sealed instance to unseal again. The root key is rotatable through the sudo-protected (sys/rotate/root) endpoint.

Read initialization status

This endpoint returns the initialization status of OpenBao.

Method	Path
GET	/sys/init

Sample request

$ curl \
    http://127.0.0.1:8200/v1/sys/init

Sample response

{
  "initialized": true
}

Start initialization

This endpoint initializes a new OpenBao. The OpenBao must not have been previously initialized. The recovery options, as well as the stored shares option, are only available when using Auto Unseal.

Method	Path
POST	/sys/init

Parameters

• pgp_keys (array<string>: nil) – Specifies an array of PGP public keys used to encrypt the output unseal keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as secret_shares.

• root_token_pgp_key (string: "") – Specifies a PGP public key used to encrypt the initial root token. The key must be base64-encoded from its original binary representation.

• secret_shares (int: <required>) – Specifies the number of shares to split the root key into.

• secret_threshold (int: <required>) – Specifies the number of shares required to reconstruct the root key. This must be less than or equal to secret_shares.

Additionally, the following options are only supported using Auto Unseal:

• stored_shares (int: <required>) – Specifies the number of shares that should be encrypted by the HSM and stored for auto-unsealing. Currently must be the same as secret_shares.

• recovery_shares (int: 0) – Specifies the number of shares to split the recovery key into. This is only available when using Auto Unseal.

• recovery_threshold (int: 0) – Specifies the number of shares required to reconstruct the recovery key. This must be less than or equal to recovery_shares. This is only available when using Auto Unseal.

• recovery_pgp_keys (array<string>: nil) – Specifies an array of PGP public keys used to encrypt the output recovery keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as recovery_shares. This is only available when using Auto Unseal.

Sample payload

{
  "secret_shares": 10,
  "secret_threshold": 5
}

Sample request

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/init

Sample response

A JSON-encoded object including the (possibly encrypted, if pgp_keys was provided) root keys, base 64 encoded root keys and initial root token:

{
  "keys": ["one", "two", "three"],
  "keys_base64": ["cR9No5cBC", "F3VLrkOo", "zIDSZNGv"],
  "root_token": "foo"
}

warning

Please be reminded that recovery keys are used as an authentication flow for rotation and regeneration of root credentials and cannot be used to unseal OpenBao in the case of the unavailability of the seal mechanism. Refer to the full warning in the documentation for Auto Unseal.