Transit secrets engine (API)

This is the API documentation for the OpenBao Transit secrets engine. For general information about the usage and operation of the Transit secrets engine, please see the transit documentation.

This documentation assumes the transit secrets engine is enabled at the /transit path in OpenBao. Since it is possible to enable secrets engines at any location, please update your API calls accordingly.

Create key

This endpoint creates a new named encryption key of the specified type. The values set here cannot be changed after key creation.

Method	Path
`POST`	`/transit/keys/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to create. This is specified as part of the URL.
convergent_encryption (bool: false) – If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. This requires derived to be set to true. When enabled, each encryption(/decryption/rewrap/datakey) operation will derive a nonce value rather than randomly generate it.
derived (bool: false) – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation.
exportable (bool: false) - Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
allow_plaintext_backup (bool: false) - If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
type (string: "aes256-gcm96") – Specifies the type of key to create. The currently-supported types are:
- aes128-gcm96 – AES-128 wrapped with GCM using a 96-bit nonce size AEAD (symmetric, supports derivation and convergent encryption)
- aes256-gcm96 – AES-256 wrapped with GCM using a 96-bit nonce size AEAD (symmetric, supports derivation and convergent encryption, default)
- chacha20-poly1305 – ChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
- xchacha20-poly1305 – XChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
- ed25519 – ED25519 (asymmetric, supports derivation). When using derivation, a sign operation with the same context will derive the same key and signature; this is a signing analogue to convergent_encryption.
- ecdsa-p256 – ECDSA using the P-256 elliptic curve (asymmetric)
- ecdsa-p384 – ECDSA using the P-384 elliptic curve (asymmetric)
- ecdsa-p521 – ECDSA using the P-521 elliptic curve (asymmetric)
- rsa-2048 - RSA with bit size of 2048 (asymmetric)
- rsa-3072 - RSA with bit size of 3072 (asymmetric)
- rsa-4096 - RSA with bit size of 4096 (asymmetric)
- hmac - HMAC (HMAC generation, verification)
key_size (int: "0", optional) - The key size in bytes for algorithms that allow variable key sizes. Currently only applicable to HMAC, where it must be between 32 and 512 bytes.
auto_rotate_period (duration: "0", optional) – The period at which this key should be rotated automatically. Setting this to "0" (the default) will disable automatic key rotation. This value cannot be shorter than one hour. Uses duration format strings.

Sample payload

{
  "type": "ecdsa-p256",
  "derived": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key

Import key

This endpoint imports existing key material into a new transit-managed encryption key. To import key material into an existing key, see the import_version/ endpoint.

This supports one of two forms:

Private/Symmetric Key import, requiring the ciphertext, hash_function parameters be set (and automatically deriving the public key), or
Public Key-only import, restricting the operations that can be done with this key, and requiring only the public_key parameter.

The remaining parameters (including name, type, allow_rotation, derived, context, exportable, allow_plaintext_backup, and auto_rotate_period) remain the same across both versions of this call.

Method	Path
`POST`	`/transit/keys/:name/import`

Parameters

name (string: <required>) – Specifies the name of the encryption key to create. This is specified as part of the URL.
ciphertext (string: <required>) - A base64-encoded string that contains two values: an ephemeral 256-bit AES key wrapped using the wrapping key returned by OpenBao and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. See the BYOK section of the Transit secrets engine documentation for more information on constructing the ciphertext. If public_key is set, this field is not required.
hash_function (string: "SHA256") - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: SHA1, SHA224, SHA256, SHA384, and SHA512. If not specified, the hash function defaults to SHA256.
type (string: <required>) – Specifies the type of key to create. The currently-supported types are:
- aes128-gcm96 – AES-128 wrapped with GCM using a 96-bit nonce size AEAD (symmetric, supports derivation and convergent encryption)
- aes256-gcm96 – AES-256 wrapped with GCM using a 96-bit nonce size AEAD (symmetric, supports derivation and convergent encryption, default)
- chacha20-poly1305 – ChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
- xchacha20-poly1305 – XChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
- ed25519 – ED25519 (asymmetric, supports derivation). When using derivation, a sign operation with the same context will derive the same key and signature; this is a signing analogue to convergent_encryption.
- ecdsa-p256 – ECDSA using the P-256 elliptic curve (asymmetric)
- ecdsa-p384 – ECDSA using the P-384 elliptic curve (asymmetric)
- ecdsa-p521 – ECDSA using the P-521 elliptic curve (asymmetric)
- rsa-2048 - RSA with bit size of 2048 (asymmetric)
- rsa-3072 - RSA with bit size of 3072 (asymmetric)
- rsa-4096 - RSA with bit size of 4096 (asymmetric)
public_key (string: "", optional) - A plaintext PEM public key to be imported. This limits the operations available under this key to verification and encryption, depending on the key type and algorithm, as no private key is available.
allow_rotation (bool: false) - If set, the imported key can be rotated within OpenBao by using the rotate endpoint.

warning

NOTE: Once an imported key is rotated within OpenBao, it will no longer support importing key material with the import_version endpoint.

derived (bool: false) – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation.
context (string: "") - A base64-encoded string providing a context for key derivation. Required if derived is set to true.
exportable (bool: false) - Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
allow_plaintext_backup (bool: false) - If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
auto_rotate_period (duration: "0", optional) – The period at which this key should be rotated automatically. Setting this to "0" (the default) will disable automatic key rotation. This value cannot be shorter than one hour.

Sample payload

{
  "type": "ed25519",
  "ciphertext": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/import

Import key version

This endpoint imports new key material into an existing imported key.

See description and note in Import Key above about importing public and private keys.

Notably, using this method, a private key matching a public key can be imported at a later date.

Method	Path
`POST`	`/transit/keys/:name/import_version`

warning

Note: Keys whose material was generated by OpenBao do not support importing key material. Only keys that were previously imported into OpenBao can import new key material from an external source.

Parameters

name (string: <required>) – Specifies the name of the encryption key to create. This is specified as part of the URL.
ciphertext (string: <required>) - A base64-encoded string that contains two values: an ephemeral 256-bit AES key wrapped using the wrapping key returned by OpenBao and the encryption of the import key material under the provided AES key. The wrapped AES key should be the first 512 bytes of the ciphertext, and the encrypted key material should be the remaining bytes. See the BYOK section of the Transit secrets engine documentation for more information on constructing the ciphertext.
hash_function (string: "SHA256") - The hash function used for the RSA-OAEP step of creating the ciphertext. Supported hash functions are: SHA1, SHA224, SHA256, SHA384, and SHA512. If not specified, the hash function defaults to SHA256.
public_key (string: "", optional) - A plaintext PEM public key to be imported. This limits the operations available under this key to verification and encryption, depending on the key type and algorithm, as no private key is available.
version (int, optional) - Key version to be updated, if left empty, a new version will be created unless a private key is specified and the 'Latest' key is missing a private key.

Sample payload

{
  "ciphertext": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/import_version

Get wrapping key

This endpoint is used to retrieve the wrapping key to use for importing keys. The returned key will be a 4096-bit RSA public key.

Method	Path
`GET`	`/transit/wrapping_key`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/transit/wrapping_key

Sample response

{
  "data": {
    "public_key": "..."
  },
}

Read key

This endpoint returns information about a named encryption key. The keys object shows the creation time of each key version; the values are not the keys themselves. Depending on the type of key, different information may be returned, e.g. an asymmetric key will return its public key in a standard format for the type.

Method	Path
`GET`	`/transit/keys/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to read. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/keys/my-key

Sample response

{
  "data": {
    "type": "aes256-gcm96",
    "deletion_allowed": false,
    "derived": false,
    "exportable": false,
    "allow_plaintext_backup": false,
    "keys": {
      "1": 1442851412
    },
    "min_decryption_version": 1,
    "min_encryption_version": 0,
    "name": "foo",
    "supports_encryption": true,
    "supports_decryption": true,
    "supports_derivation": true,
    "supports_signing": false,
    "imported": false
  }
}

The keys attribute lists each version of the key, and the time that key was created as seconds since the Unix epoch. The sample response shows a key that was created on September 22, 2015 7:50:12 PM GMT, and has not been rotated.

The fields supports_encryption, supports_decryption, supports_derivation and supports_signing are derived from the type of the key, and indicate which operations may be performed with it.

List keys

This endpoint returns a list of keys. Only the key names are returned (not the actual keys themselves).

Method	Path
`LIST`	`/transit/keys`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/transit/keys

Sample response

{
  "data": {
    "keys": ["foo", "bar"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

Delete key

This endpoint deletes a named encryption key. It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the deletion_allowed tunable must be set in the key's /config endpoint.

Method	Path
`DELETE`	`/transit/keys/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to delete. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transit/keys/my-key

Update key configuration

This endpoint allows tuning configuration values for a given key. (These values are returned during a read operation on the named key.)

Method	Path
`POST`	`/transit/keys/:name/config`

Parameters

min_decryption_version (int: 0) – Specifies the minimum version of ciphertext allowed to be decrypted. Adjusting this as part of a key rotation policy can prevent old copies of ciphertext from being decrypted, should they fall into the wrong hands. For signatures, this value controls the minimum version of signature that can be verified against. For HMACs, this controls the minimum version of a key allowed to be used as the key for verification.
min_encryption_version (int: 0) – Specifies the minimum version of the key that can be used to encrypt plaintext, sign payloads, or generate HMACs. Must be 0 (which will use the latest version) or a value greater or equal to min_decryption_version.
deletion_allowed (bool: false) - Specifies if the key is allowed to be deleted.
exportable (bool: false) - Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
allow_plaintext_backup (bool: false) - If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
auto_rotate_period (duration: "", optional) – The period at which this key should be rotated automatically. Setting this to "0" will disable automatic key rotation. This value cannot be shorter than one hour. When no value is provided, the period remains unchanged. Uses duration format strings.

Sample payload

{
  "deletion_allowed": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/config

Rotate key

This endpoint rotates the version of the named key. After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the rewrap endpoint. This is only supported with keys that support encryption and decryption operations.

For algorithms with a configurable key size, the rotated key will use the same key size as the previous version.

warning

Note: For imported keys, rotation is only supported if the allow_rotation field was set to true on import. Once an imported key is rotated within OpenBao, it will not support further import operations.

Method	Path
`POST`	`/transit/keys/:name/rotate`

Parameters

name (string: <required>) – Specifies the name of the encryption key to rotate. This is specified as part of the URL.

:::

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transit/keys/my-key/rotate

Soft delete key

This endpoint softly deletes a named encryption key, allowing it to be restored later if this deletion was done in error. This doesn't depend on the value of deletion_allowed.

The following operations will not work on the :name'd key until the key is restored:

BYOK exporting, either as a source or destination key (/transit/byok-export/:dest/:name and /transit/byok-export/:name/:src),
Exporting (/transit/export/:key_type/:name),
Encrypting and decrypting (/transit/encrypt/:name and /transit/decrypt/:name),
Signing and verifying including with HMAC keys (/transit/sign/:name, /transit/hmac/:name, and /transit/verify/:name), and
Rotating the specified key (/transit/keys/:name/rotate).

However, this key will still be able to be updated, backed up, read, and will appear in list operations.

Method	Path
`DELETE`	`/transit/keys/:name/soft-delete`

Parameters

name (string: <required>) – Specifies the name of the encryption key to softly delete. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transit/keys/my-key/soft-delete

Restore soft deleted key

This endpoint restores a softly deleted named encryption key, allowing it to be used again.

Method	Path
`POST`	`/transit/keys/:name/soft-delete-restore`

Parameters

name (string: <required>) – Specifies the name of the encryption key to restore from soft deletion. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transit/keys/my-key/soft-delete-restore

Securely export key

This endpoint returns a wrapped copy of the source key, protected by the destination key using BYOK method accepted by the /transit/keys/:name/import API. This allows an operator using two separate OpenBao instances to secure established shared key material, withing exposing either key in plaintext and needing to run a manual BYOK import using the CLI helper utility.

Method	Path
`GET`	`/transit/byok-export/:destination/:source(/:version)`

Parameters

destination (string: <required>) - Specifies the name of the key to encrypt the source key to: this is usually another mount or cluster's wrapping key (from /transit/wrapping_key). This is specified as part of the URL.

warning

Note: This destination key type must be an RSA key type.

source (string: <required>) - Specifies the source key to encrypt, to copy (encrypted) to another cluster. This is specified as part of the URL.
version (string: "") - Specifies the version of the source key to wrap. If omitted, all versions of the key will be returned. This is specified as part of the URL. If the version is set to latest, the current key will be returned.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/byok-export/wrapping-key/to-be-shared-key/1

Sample response

{
  "data": {
    "name": "foo",
    "keys": {
      "1": "H/0T+CKQ8I82KJWpPk ... additional response elided ...",
    }
  }
}

Export key

This endpoint returns the named key. The keys object shows the value of the key for each version. If version is specified, the specific version will be returned. If latest is provided as the version, the current key will be provided. Depending on the type of key, different information may be returned. The key must be exportable to support this operation and the version must still be valid.

Method	Path
`GET`	`/transit/export/:key_type/:name(/:version)`

Parameters

key_type (string: <required>) – Specifies the type of the key to export. This is specified as part of the URL. Valid values are:
- encryption-key
- signing-key
- hmac-key
- public-key, to return the corresponding public keys of private key asymmetric keys (EC with NIST P-curves or Ed25519 and RSA).
name (string: <required>) – Specifies the name of the key to read information about. This is specified as part of the URL.
version (string: "") – Specifies the version of the key to read. If omitted, all versions of the key will be returned. This is specified as part of the URL. If the version is set to latest, the current key will be returned.
format (string: "") - Specifies the format of the exported key. The empty string preserves existing behavior, with format unique to each key type (base64 encoded raw keys for symmetric keys or Ed25519 keys, PKCS#1 for RSA private keys, SEC 1 for EC private keys, and PKIX format for RSA or EC public keys). The raw format always returns a base64 encoded raw key (only applicable to symmetric keys and Ed25519 keys). The der and pem formats always returns a PKIX (SubjectPublicKeyInfo) or PrivateKeyInfo encoded object for asymmetric keys.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/export/encryption-key/my-key/1

Sample response

{
  "data": {
    "name": "foo",
    "keys": {
      "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=",
      "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE="
    }
  }
}

Write keys configuration

This endpoint maintains global configuration across all keys. This allows removing the upsert capability of the /encrypt/:key endpoint, preventing new keys from being created if none exists.

Method	Path
`POST`	`/transit/config/keys`

Parameters

disable_upsert (bool: false) - Specifies whether to disable upserting on encryption (automatic creation of unknown keys).

Sample payload

{
  "disable_upsert": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/config/keys

Sample response

{
  "data": {
    "disable_upsert": true,
  }
}

Read keys configuration

This endpoint maintains global configuration across all keys. This allows removing the upsert capability of the /encrypt/:key endpoint, preventing new keys from being created if none exists.

Method	Path
`GET`	`/transit/config/keys`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/config/keys

Sample response

{
  "data": {
    "disable_upsert": false,
  }
}

Encrypt data

This endpoint encrypts the provided plaintext using the named key. This path supports the create and update policy capabilities as follows: if the user has the create capability for this endpoint in their policies, and the key does not exist, it will be upserted with default values (whether the key requires derivation depends on whether the context parameter is empty or not). If the user only has update capability and the key does not exist, an error will be returned.

warning

Note: If upsert is disallowed by global keys configuration, create requests will behave like update requests.

Method	Path
`POST`	`/transit/encrypt/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to encrypt against. This is specified as part of the URL.
plaintext (string: <required>) – Specifies base64 encoded plaintext to be encoded.
associated_data (string: "") - Specifies base64 encoded associated data (also known as additional data or AAD) to also be authenticated with AEAD ciphers (aes128-gcm96, aes256-gcm, chacha20-poly1305, and xchacha20-poly1305).
context (string: "") – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled for this key.
key_version (int: 0) – Specifies the version of the key to use for encryption. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
nonce (string: "") – Specifies the base64 encoded nonce value. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items to be encrypted in a single batch. When this parameter is set, if the parameters 'plaintext' and 'context' are also set, they will be ignored. Any batch output will preserve the order of the batch input. The format for the input is:
```
[
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="
  }
]
```
type (string: "aes256-gcm96") –This parameter is required when encryption key is expected to be created. When performing an upsert operation, the type of key to create.
convergent_encryption (string: "") – This parameter will only be used when a key is expected to be created. Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) for AES and ChaCha20 or 192-bit (24-byte) for XChaCha20 nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext's security.
partial_failure_response_code (int: 400) Ordinarily, if a batch item fails to encrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a failed status code in this case. If all values fail an error code is still returned. Be warned that some failures (such as failure to decrypt) could be indicative of a security breach and should not be ignored.

warning

NOTE: All plaintext data must be base64-encoded. The reason for this requirement is that OpenBao does not require that the plaintext is "text". It could be a binary file such as a PDF or image. The easiest safe transport mechanism for this data as part of a JSON payload is to base64-encode it.

Sample payload

Fist, encode the plaintext with base64:

$ echo "the quick brown fox" | base64
dGhlIHF1aWNrIGJyb3duIGZveAo=

Use the base64-encoded plaintext in the payload:

{
  "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo="
}

danger

OpenBao HTTP API imposes a maximum request size of 32MB to prevent a denial of service attack. This can be tuned per listener block in the OpenBao server configuration.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/encrypt/my-key

Sample response

{
  "data": {
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
}

Decrypt data

This endpoint decrypts the provided ciphertext using the named key.

Method	Path
`POST`	`/transit/decrypt/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to decrypt against. This is specified as part of the URL.
ciphertext (string: <required>) – Specifies the ciphertext to decrypt.
associated_data (string: "") - Specifies base64 encoded associated data (also known as additional data or AAD) to also be authenticated with AEAD ciphers (aes128-gcm96, aes256-gcm, chacha20-poly1305, and xchacha20-poly1305).
context (string: "") – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.
nonce (string: "") – Specifies a base64 encoded nonce value used during encryption.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters 'ciphertext' and 'context' are also set, they will be ignored. Any batch output will preserve the order of the batch input. Format for the input goes like this:
```
[
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
]
```
partial_failure_response_code (int: 400) Ordinarily, if a batch item fails to encrypt due to a bad input, but other batch items succeed, the HTTP response code is 400 (Bad Request). Some applications may want to treat partial failures differently. Providing the parameter returns the given response code integer instead of a failed status code in this case. If all values fail an error code is still returned. Be warned that some failures (such as failure to decrypt) could be indicative of a security breach and should not be ignored.

Sample payload

{
  "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/decrypt/my-key

Sample response

{
  "data": {
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

Rewrap data

This endpoint rewraps the provided ciphertext using the latest version of the named key. Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.

Method	Path
`POST`	`/transit/rewrap/:name`

Parameters

name (string: <required>) – Specifies the name of the encryption key to re-encrypt against. This is specified as part of the URL.
ciphertext (string: <required>) – Specifies the ciphertext to re-encrypt.
context (string: "") – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.
key_version (int: 0) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
nonce (string: "") – Specifies a base64 encoded nonce value used during encryption.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items to be re-encrypted in a single batch. When this parameter is set, if the parameters 'ciphertext' and 'context' are also set, they will be ignored. Any batch output will preserve the order of the batch input. Format for the input goes like this:
```
[
  {
    "context": "c2FtcGxlY29udGV4dA==",
    "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI="
  },
  {
    "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=",
    "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
  }
]
```

Sample payload

{
  "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/rewrap/my-key

Sample response

{
  "data": {
    "ciphertext": "vault:v2:abcdefgh"
  }
}

Generate data key

This endpoint generates a new high-entropy key and the value encrypted with the named key. Optionally return the plaintext of the key as well. Whether plaintext is returned depends on the path; as a result, you can use OpenBao ACL policies to control whether a user is allowed to retrieve the plaintext value of a key. This is useful if you want an untrusted user or operation to generate keys that are then made available to trusted users.

Method	Path
`POST`	`/transit/datakey/:type/:name`

Parameters

type (string: <required>) – Specifies the type of key to generate. If plaintext, the plaintext key will be returned along with the ciphertext. If wrapped, only the ciphertext value will be returned. This is specified as part of the URL.
name (string: <required>) – Specifies the name of the encryption key to use to encrypt the datakey. This is specified as part of the URL.
context (string: "") – Specifies the key derivation context, provided as a base64-encoded string. This must be provided if derivation is enabled.
nonce (string: "") – Specifies a nonce value, provided as base64 encoded. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
bits (int: 256) – Specifies the number of bits in the desired key. Can be 128, 256, or 512.

Sample payload

{
  "context": "Ab3=="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/datakey/plaintext/my-key

Sample response

{
  "data": {
    "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=",
    "ciphertext": "vault:v1:abcdefgh"
  }
}

Generate random bytes

This endpoint returns high-quality random bytes of the specified length.

Method	Path
`POST`	`/transit/random(/:source)(/:bytes)`

Parameters

bytes (int: 32) – Specifies the number of bytes to return. This value can be specified either in the request body, or as a part of the URL.
format (string: "base64") – Specifies the output encoding. Valid options are hex or base64.
source (string: "platform") - Specifies the source of the requested bytes. platform, the default, sources bytes from the platform's entropy source. all mixes bytes from all available sources.

Sample payload

{
  "format": "hex"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/random/164

Sample response

{
  "data": {
    "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

Hash data

This endpoint returns the cryptographic hash of given data using the specified algorithm.

Method	Path
`POST`	`/transit/hash(/:algorithm)`

Parameters

algorithm (string: "sha2-256") – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are:
- sha2-224
- sha2-256
- sha2-384
- sha2-512
- sha3-224
- sha3-256
- sha3-384
- sha3-512

warning

Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: sha3-224, sha3-256, sha3-384, and sha3-512.

input (string: <required>) – Specifies the base64 encoded input data.
format (string: "hex") – Specifies the output encoding. This can be either hex or base64.

Sample payload

{
  "input": "adba32=="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/hash/sha2-512

Sample response

{
  "data": {
    "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

Generate HMAC

This endpoint returns the digest of given data using the specified hash algorithm and the named key. The key can be of any type supported by transit, as each transit key version has an independent, random 256-bit HMAC secret key. If the key is of a type that supports rotation, the latest (current) version will be used.

Method	Path
`POST`	`/transit/hmac/:name(/:algorithm)`

Parameters

name (string: <required>) – Specifies the name of the encryption key to generate hmac against. This is specified as part of the URL.
key_version (int: 0) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
algorithm (string: "sha2-256") – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are:
- sha2-224
- sha2-256
- sha2-384
- sha2-512
- sha3-224
- sha3-256
- sha3-384
- sha3-512

warning

Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: sha3-224, sha3-256, sha3-384, and sha3-512.

input (string: "") – Specifies the base64 encoded input data. One of input or batch_input must be supplied.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items for processing. When this parameter is set, if the parameter 'input' is also set, it will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input. If the input data value of an item is invalid, the corresponding item in the 'batch_results' will have the key 'error' with a value describing the error. The format for batch_input is:
```
{
  "batch_input": [
    {
      "input": "adba32=="
    },
    {
      "input": "aGVsbG8gd29ybGQuCg=="
    }
  ]
}
```

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/hmac/my-key/sha2-512

Sample payload

{
  "input": "adba32=="
}

Sample response

{
  "data": {
    "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo="
  }
}

Sample payload with batch_input

{
  "batch_input": [
    {
      "input": "adba32=="
    },
    {
      "input": "adba32=="
    },
    {},
    {
      "input": ""
    }
  ]
}

Sample response for batch_input

{
  "data": {
    "batch_results": [
      {
        "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP"
      },
      {
        "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP"
      },
      {
        "error": "missing input for HMAC"
      },
      {
        "hmac": "vault:v1:/wsSP6iQ9ECO9RRkefKLXey9sDntzSjoiW0vBrWfUsYB0ISroyC6plUt/jN7gcOv9O+Ecow"
      }
    ]
  }
}

Sign data

This endpoint returns the cryptographic signature of the given data using the named key and the specified hash algorithm. The key must be of a type that supports signing.

Method	Path
`POST`	`/transit/sign/:name(/:hash_algorithm)`

Parameters

name (string: <required>) – Specifies the name of the encryption key to use for signing. This is specified as part of the URL.
key_version (int: 0) – Specifies the version of the key to use for signing. If not set, uses the latest version. Must be greater than or equal to the key's min_encryption_version, if set.
hash_algorithm (string: "sha2-256") – Specifies the hash algorithm to use for supporting key types (notably, not including ed25519 which specifies its own hash algorithm). This can also be specified as part of the URL. Currently-supported algorithms are:
- sha1
- sha2-224
- sha2-256
- sha2-384
- sha2-512
- sha3-224
- sha3-256
- sha3-384
- sha3-512
- none

warning

Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: sha3-224, sha3-256, sha3-384, and sha3-512.

warning

** Warning:** sha1 should be considered a compromised algorithm and used only for legacy applications. Signing using SHA-1 can be blocked by operators by assigning the following policy corresponding to a named key:

path "/transit/sign/:name/sha1" {
  capabilities = ["deny"]
}

warning

Note: using hash_algorithm=none requires setting prehashed=true and signature_algorithm=pkcs1v15. This generates a PKCSv1_5_NoOID signature rather than the PKCSv1_5_DERnull signature type usually created. See RFC 3447 Section 9.2.

input (string: "") – Specifies the base64 encoded input data. One of input or batch_input must be supplied.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items for processing. When this parameter is set, any supplied 'input' or 'context' parameters will be ignored. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input. If the input data value of an item is invalid, the corresponding item in the 'batch_results' will have the key 'error' with a value describing the error. The format for batch_input is:
```
{
  "batch_input": [
    {
      "input": "adba32==",
      "context": "abcd"
    },
    {
      "input": "aGVsbG8gd29ybGQuCg==",
      "context": "efgh"
    }
  ]
}
```
context (string: "") - Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
prehashed (bool: false) - Set to true when the input is already hashed. If the key type is rsa-2048, rsa-3072 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter. Just as the value to sign should be the base64-encoded representation of the exact binary data you want signed, when set, input is expected to be base64-encoded binary hashed data, not hex-formatted. (As an example, on the command line, you could generate a suitable input via openssl dgst -sha256 -binary | base64.)
signature_algorithm (string: "pss") – When using a RSA key, specifies the RSA signature algorithm to use for signing. Supported signature types are:
- pss
- pkcs1v15
marshaling_algorithm (string: "asn1") – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are:
- asn1: The default, used by OpenSSL and X.509
- jws: The version used by JWS (and thus for JWTs). Selecting this will also change the output encoding to URL-safe Base64 encoding instead of standard Base64-encoding.
salt_length (string: "auto") – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. Options are:
- auto: The default used by Golang (causing the salt to be as large as possible when signing)
- hash: Causes the salt length to equal the length of the hash used in the signature
- An integer between the minimum and the maximum permissible salt lengths for the given RSA key size.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/sign/my-key/sha2-512

Sample payload

{
  "input": "adba32=="
}

Sample response

{
  "data": {
    "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI="
  }
}

Sample payload with batch_input

Given an ed25519 key with derived keys set, the context parameter is expected for each batch_input item, and the response will include the derived public key for each item.

{
  "batch_input": [
    {
      "input": "adba32==",
      "context": "efgh"
    },
    {
      "input": "adba32==",
      "context": "abcd"
    },
    {}
  ]
}

Sample response for batch_input

{
  "data": {
    "batch_results": [
      {
        "signature": "vault:v1:+R3cxAy6j4KriYzAyExU6p1glnyT/eLDSaUZO7gr8a8kgi/zSynNbOBSDJcGaAfLD1OF2hGupYBYTjmZMNoVAA==",
        "publickey": "2fQIaaem7+EhSGs3jUebAS/8qP2+sUrmxOmgqZIZc0c="
      },
      {
        "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA==",
        "publickey": "goDXuePo7L9z6HOw+a54O4HeV189BLECK9nAUudwp4Y="
      },
      {
        "error": "missing input"
      }
    ]
  },
}

Verify signed data

This endpoint returns whether the provided signature is valid for the given data.

Method	Path
`POST`	`/transit/verify/:name(/:hash_algorithm)`

Parameters

name (string: <required>) – Specifies the name of the encryption key that was used to generate the signature or HMAC.
hash_algorithm (string: "sha2-256") – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are:
- sha1
- sha2-224
- sha2-256
- sha2-384
- sha2-512
- sha3-224
- sha3-256
- sha3-384
- sha3-512
- none

warning

Note: In FIPS 140-2 mode, the following algorithms are not certified and thus should not be used: sha3-224, sha3-256, sha3-384, and sha3-512.

warning

** Warning:** sha1 should be considered a compromised algorithm. Signatures verified using the algorithm could be forgeries. Verification using SHA-1 can be blocked by operators by assigning the following policy corresponding to a named key:

path "/transit/verify/:name/sha1" {
  capabilities = ["deny"]
}

warning

Note: using hash_algorithm=none requires setting prehashed=true and signature_algorithm=pkcs1v15. This verifies a PKCSv1_5_NoOID signature rather than the PKCSv1_5_DERnull signature type usually verified. See RFC 3447 Section 9.2.

input (string: "") – Specifies the base64 encoded input data. One of input or batch_input must be supplied.
signature (string: "") – Specifies the signature output from the /transit/sign function. Either this must be supplied or hmac must be supplied.
hmac (string: "") – Specifies the signature output from the /transit/hmac function. Either this must be supplied or signature must be supplied.
reference (string: "") - A user-supplied string that will be present in the reference field on the corresponding batch_results item in the response, to assist in understanding which result corresponds to a particular input. Only valid on batch requests when using ‘batch_input’ below.
batch_input (array<object>: nil) – Specifies a list of items for processing. When this parameter is set, any supplied 'input', 'hmac' or 'signature' parameters will be ignored. 'batch_input' items should contain an 'input' parameter and either an 'hmac' or 'signature' parameter. All items in the batch must consistently supply either 'hmac' or 'signature' parameters. It is an error for some items to supply 'hmac' while others supply 'signature'. Responses are returned in the 'batch_results' array component of the 'data' element of the response. Any batch output will preserve the order of the batch input. If the input data value of an item is invalid, the corresponding item in the 'batch_results' will have the key 'error' with a value describing the error. The format for batch_input is:
```
{
  "batch_input": [
    {
      "input": "adba32==",
      "hmac": "vault:v1:1jFhRYWHiddSKgEFyVRpX8ieX7UU+748NBwHKecXE3hnGBoAxrfgoD5U0yAvji7b5X6V1fP"
    },
    {
      "input": "aGVsbG8gd29ybGQuCg==",
      "hmac": "vault:v1:/wsSP6iQ9ECO9RRkefKLXey9sDntzSjoiW0vBrWfUsYB0ISroyC6plUt/jN7gcOv9O+Ecow"
    }
  ]
}
```
context (string: "") - Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
prehashed (bool: false) - Set to true when the input is already hashed. If the key type is rsa-2048, rsa-3072 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter.
signature_algorithm (string: "pss") – When using a RSA key, specifies the RSA signature algorithm to use for signature verification. Supported signature types are:
- pss
- pkcs1v15
marshaling_algorithm (string: "asn1") – Specifies the way in which the signature was originally marshaled. This currently only applies to ECDSA keys. Supported types are:
- asn1: The default, used by OpenSSL and X.509
- jws: The version used by JWS (and thus for JWTs). Selecting this will also expect the input encoding to URL-safe Base64 encoding instead of standard Base64-encoding.
salt_length (string: "auto") – The salt length used to sign. This currently only applies to the RSA PSS signature scheme. Options are:
- auto: The default used by Golang (causing the salt to be as large as possible when signing)
- hash: Causes the salt length to equal the length of the hash used in the signature
- An integer between the minimum and the maximum permissible salt lengths for the given RSA key size.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/verify/my-key/sha2-512

Sample payload

{
  "input": "abcd13==",
  "signature": "vault:v1:MEUCIQCyb869d7KWuA..."
}

Sample response

{
  "data": {
    "valid": true
  }
}

Sample payload with batch_input

{
  "batch_input": [
    {
      "input": "adba32==",
      "context": "abcd",
      "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA=="
    },
    {
      "input": "adba32==",
      "context": "efgh",
      "signature": "vault:v1:3hBwA88lnuAVJqb5rCCEstzKYaBTeSdejk356BTCE/nKwySOhzQH3mWCvJZwbRptNGa7ia5ykosYYdJz+aIKDA=="
    },
    {
      "input": "",
      "context": "abcd",
      "signature": "vault:v1:C/pxm5V1RI6kqudLdbLdj5Bpm2P38FKgvxoV69oNXphvJukRcQIqjZO793jCa2JPYPG21Y7vquDWy/Ff4Ma4AQ=="
    }
  ]
}

Sample response for batch_input

{
  "data": {
    "batch_results": [
      {
        "valid": true
      },
      {
        "valid": false
      },
      {
        "valid": true
      }
    ]
  },
}

Backup key

This endpoint returns a plaintext backup of a named key. The backup contains all the configuration data and keys of all the versions along with the HMAC key. The response from this endpoint can be used with the /restore endpoint to restore the key.

Method	Path
`GET`	`/transit/backup/:name`

Parameters

name (string: <required>) - Name of the key.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transit/backup/aes

Sample response

{
  "data": {
    "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg=="
  }
}

Restore key

This endpoint restores the backup as a named key. This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this endpoint should be the output of /backup endpoint.

warning

For safety, by default the backend will refuse to restore to an existing key. If you want to reuse a key name, it is recommended you delete the key before restoring. It is a good idea to attempt restoring to a different key name first to verify that the operation successfully completes.

Method	Path
`POST`	`/transit/restore(/:name)`

Parameters

backup (string: <required>) - Backed up key data to be restored. This should be the output from the /backup endpoint.
name (string: <optional>) - If set, this will be the name of the restored key.
force (bool: false) - If set, force the restore to proceed even if a key by this name already exists.

Sample payload

{
    "backup": "eyJwb2xpY3kiOnsibmFtZSI6ImFlcyIsImtleXMiOnsiMSI6eyJrZXkiOiJXK3k4Z0dOMHdiTDJLOU95NXFPN1laMGtjdzMvR0ZiNWM4STBzdlNMMnFNPSIsImhtYWNfa2V5IjoiUDBTcjh1YTJaZERNUTdPd2h4RGp1Z0U5d0JSR3Q2QXl6K0t4TzN5Z2M5ST0iLCJ0aW1lIjoiMjAxNy0xMi0wOFQxMTo1MDowOC42MTM4MzctMDU6MDAiLCJlY194IjpudWxsLCJlY195IjpudWxsLCJlY19kIjpudWxsLCJyc2Ffa2V5IjpudWxsLCJwdWJsaWNfa2V5IjoiIiwiY3JlYXRpb25fdGltZSI6MTUxMjc1MTgwOH19LCJkZXJpdmVkIjpmYWxzZSwia2RmIjowLCJjb252ZXJnZW50X2VuY3J5cHRpb24iOmZhbHNlLCJleHBvcnRhYmxlIjpmYWxzZSwibWluX2RlY3J5cHRpb25fdmVyc2lvbiI6MSwibWluX2VuY3J5cHRpb25fdmVyc2lvbiI6MCwibGF0ZXN0X3ZlcnNpb24iOjEsImFyY2hpdmVfdmVyc2lvbiI6MSwiZGVsZXRpb25fYWxsb3dlZCI6ZmFsc2UsImNvbnZlcmdlbnRfdmVyc2lvbiI6MCwidHlwZSI6MCwiYmFja3VwX2luZm8iOnsidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MjkuMjI4MTU3LTA1OjAwIiwidmVyc2lvbiI6MX0sInJlc3RvcmVfaW5mbyI6bnVsbH0sImFyY2hpdmVkX2tleXMiOnsia2V5cyI6W3sia2V5IjpudWxsLCJobWFjX2tleSI6bnVsbCwidGltZSI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjB9LHsia2V5IjoiVyt5OGdHTjB3YkwySzlPeTVxTzdZWjBrY3czL0dGYjVjOEkwc3ZTTDJxTT0iLCJobWFjX2tleSI6IlAwU3I4dWEyWmRETVE3T3doeERqdWdFOXdCUkd0NkF5eitLeE8zeWdjOUk9IiwidGltZSI6IjIwMTctMTItMDhUMTE6NTA6MDguNjEzODM3LTA1OjAwIiwiZWNfeCI6bnVsbCwiZWNfeSI6bnVsbCwiZWNfZCI6bnVsbCwicnNhX2tleSI6bnVsbCwicHVibGljX2tleSI6IiIsImNyZWF0aW9uX3RpbWUiOjE1MTI3NTE4MDh9XX19Cg=="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/restore

Trim key

This endpoint trims older key versions setting a minimum version for the keyring. Once trimmed, previous versions of the key cannot be recovered.

Method	Path
`POST`	`/transit/keys/:name/trim`

Parameters

min_available_version (int: <required>) - The minimum available version for the key ring. All versions before this version will be permanently deleted. This value can at most be equal to the lesser of min_decryption_version and min_encryption_version. This is not allowed to be set when either min_encryption_version or min_decryption_version is set to zero.

Sample payload

{
  "min_available_version": 2
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/trim

Configure cache

This endpoint is used to configure the transit engine's cache. Note that configuration changes will not be applied until the transit plugin is reloaded which can be achieved using the [/sys/plugins/reload/backend][sys-plugin-reload-backend] endpoint.

Method	Path
`POST`	`/transit/cache-config`

Parameters

size (int: 0) - Specifies the size in terms of number of entries. A size of 0 means unlimited. A Least Recently Used (LRU) caching strategy is used for a non-zero cache size. Must be 0 (default) or a value greater or equal to 10 (minimum cache size).

Sample payload

{
  "size": 456
}

Sample request

$ curl \
    --header "X-Vault-Token: ..."
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/cache-config

Read transit cache configuration

This endpoint retrieves configurations for the transit engine's cache.

Method	Path
`GET`	`/transit/cache-config`

Sample request

$ curl \
    --header "X-Vault-Token: ..."
    --request GET \
    http://127.0.0.1:8200/v1/transit/cache-config

Sample response

  "data": {
    "size": 0
  },

Sign CSR

This endpoint signs a CSR using the :name key, ensuring the key material stays within Transit. If no CSR is provided, it signs an empty CSR. Otherwise, it signs the provided CSR, replacing its key material with the :name key material. The key in transit must be a signing key and not be derived.

Method	Path
`POST`	`/transit/keys/:name/csr`

Parameters

name (string: <required>) - Specifies the name of the key to sign the CSR with. This is specified as part of the URL.
version (int, optional) - The version of the key to use for signing. If the version is set to latest or is not set, the current key will be returned.
csr (string, optional) - Optional PEM-encoded CSR template to use as a basis for the new CSR signed by this key. If not set, an empty CSR is used.

Sample payload

{
  "version": 3,
  "csr": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/csr

Sample response

{
  "data": {
    "name": "my-key",
    "type": "rsa-2048",
    "csr": "..."
  }
}

Set Certificate Chain

This endpoint sets the certificate chain for the :name key, ensuring the key material stays within Transit and certificates are managed in one place. It also allows chain updates and rotation, as it will overwrite any existing certificate chain.

Method	Path
`POST`	`/transit/keys/:name/set-certificate`

Parameters

name (string: <required>) - Specifies the name of the key to import the certificate chain against. This is specified as part of the URL.
version (int, optional) - Specifies the version of the key to import the certificate chain against. If the version is set to latest or is not set, the current key will be returned.
certificate_chain (string: <required>) - A PEM encoded certificate chain. It should be composed by one or more concatenated PEM blocks and ordered starting from the end-entity certificate.

Sample payload

{
  "version": 3,
  "certificate_chain": "..."
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transit/keys/my-key/set-certificate

Sample response

{
  "data": {
    "name": "my-key",
    "type": "rsa-2048",
    "certificate_chain": "..."
  }
}

Create key​

Parameters​

Sample payload​

Sample request​

Import key​

Parameters​

Sample payload​

Sample request​

Import key version​

Parameters​

Sample payload​

Sample request​

Get wrapping key​

Sample request​

Sample response​

Read key​

Parameters​

Sample request​

Sample response​

List keys​

Parameters​

Sample request​

Sample response​

Delete key​

Parameters​

Sample request​

Update key configuration​

Parameters​

Sample payload​

Sample request​

Rotate key​

Parameters​

Sample request​

Soft delete key​

Parameters​

Sample request​

Restore soft deleted key​

Parameters​

Sample request​

Securely export key​

Parameters​

Sample request​

Sample response​

Export key​

Parameters​

Sample request​

Sample response​

Write keys configuration​

Parameters​

Sample payload​

Sample request​

Sample response​

Read keys configuration​

Sample request​

Sample response​

Encrypt data​

Parameters​

Sample payload​

Sample request​

Sample response​

Decrypt data​

Parameters​

Sample payload​

Sample request​

Sample response​

Rewrap data​

Parameters​

Sample payload​

Sample request​

Sample response​

Generate data key​

Parameters​

Sample payload​

Sample request​

Sample response​

Generate random bytes​

Parameters​

Sample payload​

Sample request​

Sample response​

Create key

Parameters

Sample payload

Sample request

Import key

Parameters

Sample payload

Sample request

Import key version

Parameters

Sample payload

Sample request

Get wrapping key

Sample request

Sample response

Read key

Parameters

Sample request

Sample response

List keys

Parameters

Sample request

Sample response

Delete key

Parameters

Sample request

Update key configuration

Parameters

Sample payload

Sample request

Rotate key

Parameters

Sample request

Soft delete key

Parameters

Sample request

Restore soft deleted key

Parameters

Sample request

Securely export key

Parameters

Sample request

Sample response

Export key

Parameters

Sample request

Sample response

Write keys configuration

Parameters

Sample payload

Sample request

Sample response

Read keys configuration

Sample request

Sample response

Encrypt data

Parameters

Sample payload

Sample request

Sample response

Decrypt data

Parameters

Sample payload

Sample request

Sample response

Rewrap data

Parameters

Sample payload

Sample request

Sample response

Generate data key

Parameters

Sample payload

Sample request

Sample response

Generate random bytes

Parameters

Sample payload

Sample request

Sample response