Skip to main content

/sys/init

The /sys/init endpoint is used to initialize a new OpenBao.

Read initialization status​

This endpoint returns the initialization status of OpenBao.

MethodPath
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.

MethodPath
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 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 rekeying 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.