Transform secrets engine (API)

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

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

Create/Update role

This endpoint creates or updates the role with the given name. If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/role/:name`

Parameters

name (string: <required>) – Specifies the name of the role to create. This is part of the request URL.
transformations (list: []) - Specifies the transformations that can be used with this role.

Sample payload

{
  "transformations": ["creditcard-fpe", "creditcard-masking"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/role/example-role

Read role

This endpoint queries an existing role by the given name.

Method	Path
`GET`	`/transform/role/:name`

Parameters

name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/role/example-role

Sample response

{
  "data": {
    "transformations": ["creditcard-fpe", "creditcard-masking"]
  }
}

List roles

This endpoint lists all existing roles in the secrets engine.

Method	Path
`LIST`	`/transform/role`

Parameters

filter (string: "*") – If provided, only returns role names that match the given glob.

Sample request

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

Sample response

{
  "data": {
    "keys": ["example-role"]
  }
}

Delete role

This endpoint deletes an existing role by the given name.

Method	Path
`DELETE`	`/transform/role/:name`

Parameters

name (string: <required>) – Specifies the name of the role to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transform/role/example-role

Create/Update transformation ^{DEPRECATED (1.6)}

This endpoint creates or updates a transformation with the given name. If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes. This endpoint is deprecated as of version 1.6 in favor of the type specific configuration endpoints, and will be removed in a future release.

Method	Path
`POST`	`/transform/transformation/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to create or update. This is part of the request URL.
type (string: <required>) - Specifies the type of transformation to perform. The types currently supported by this backend are fpe, masking, and tokenization. This value cannot be modified by an update operation after creation.
template (string: <required>) - Specifies the template name to use for matching value on encode and decode operations when using this transformation. Ignored by the tokenization transformation type.
tweak_source (string: "supplied") - Specifies the source of where the tweak value comes from. Valid sources are supplied, generated, and internal. Only used when the type is FPE.
masking_character (string: "*") - Specifies the character to use for masking. If multiple characters are provided, only the first one is used and the rest is ignored. Only used when the type is masking.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.
deletion_allowed (bool: false) - If true, this transform can be deleted. Otherwise deletion is blocked while this value remains false.

Sample payload

{
  "type": "fpe",
  "template": "builtin/creditcardnumber",
  "tweak_source": "internal",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformation/example-transformation

Create/Update FPE transformation

This endpoint creates or updates an FPE transformation with the given name. If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/transformations/fpe/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to create or update. This is part of the request URL.
template (string: <required>) - Specifies the template name to use for matching value on encode and decode operations when using this transformation.
tweak_source (string: "supplied") - Specifies the source of where the tweak value comes from. Valid sources are supplied, generated, and internal. Only used when the type is FPE.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.
deletion_allowed (bool: false) - If true, this transform can be deleted. Otherwise deletion is blocked while this value remains false. Note that deleting the transform deletes the underlying key making decoding of FPE encoded values impossible without restoring from a backup.

Sample payload

{
  "template": "builtin/creditcardnumber",
  "tweak_source": "internal",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/fpe/example-transformation

Create/Update masking transformation

This endpoint creates or updates a masking transformation with the given name. If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/transformations/masking/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to create or update. This is part of the request URL.
template (string: <required>) - Specifies the template name to use for matching value on encode and decode operations when using this transformation.
masking_character (string: "*") - Specifies the character to use for masking. If multiple characters are provided, only the first one is used and the rest is ignored. Only used when the type is masking.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.

Sample payload

{
  "template": "builtin/creditcardnumber",
  "masking_character": "X",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/masking/example-transformation

Create/Update tokenization transformation

This endpoint creates or updates a tokenization transformation with the given name. If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/transformations/tokenization/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to create or update. This is part of the request URL.
mapping_mode (string: "default") - Specifies the mapping mode for stored tokenization values. default is strongly recommended for highest security. exportable allows for all plaintexts to be decoded via the export-decoded endpoint in an emergency.
convergent (bool: false) - Specifies whether to use convergent tokenization, where tokenization of the same plaintext more than once results in the same token. Defaults to false as unique tokens are more desirable from a security standpoint if there isn't a use-case need for convergence. This property cannot be changed after the transform is created.
max_ttl: (duration: "0") - The maximum TTL of a token. If 0 or unspecified, tokens may have no expiration.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.
stores (list: ["builtin/internal"]) - The list of tokenization stores to use for tokenization state. Vault's internal storage is used by default.
deletion_allowed (bool: false) - If true, this transform can be deleted. Otherwise deletion is blocked while this value remains false. Note that deleting the transform deletes the underlying key making decoding of tokenized values impossible without restoring from a backup.

Sample payload

{
  "max_ttl": "365d",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/tokenization/example-transformation

Import key for FPE transformation

This endpoint imports an existing AES-256 key into a new FPE transformation. Currently, importing a key into an existing FPE transformation is not supported.

Method	Path
`POST`	`/transform/transformations/fpe/: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 Vault 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.
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.
template (string: <required>) - Specifies the template name to use for matching value on encode and decode operations when using this transformation.
tweak_source (string: "supplied") - Specifies the source of where the tweak value originated. Valid sources are supplied, generated, and internal. Only used when the type is FPE.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list for the encode and decode operations to function properly.

Sample payload

{
  "ciphertext": "...",
  "template": "builtin/creditcardnumber",
  "tweak_source": "internal",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/fpe/example-transformation/import

Import key for tokenization transformation

This endpoint imports an existing AES-256 key into a new tokenization transformation. To import key material into an existing key, see the tokenization import_version/ endpoint.

Note: At this time, tokenization transformations with imported keys do not support convergent tokenization.

Method	Path
`POST`	`/transform/transformations/tokenization/: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 Vault 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.
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.
allow_rotation (bool: false) - If set, the imported key can be rotated within Vault by using the rotate endpoint.

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

mapping_mode (string: "default") - Specifies the mapping mode for stored tokenization values. default is strongly recommended for highest security. exportable allows for all plaintexts to be decoded via the export-decoded endpoint in an emergency.
max_ttl: (duration: "0") - The maximum TTL of a token. If 0 or unspecified, tokens may have no expiration.
allowed_roles (list: []) - Specifies a list of allowed roles that this transformation can be assigned to. A role using this transformation must exist in this list in order for encode and decode operations to properly function.
stores (list: ["builtin/internal"]) - The list of tokenization stores to use for tokenization state. Vault's internal storage is used by default.

Sample payload

{
  "ciphertext": "...",
  "max_ttl": "365d",
  "allowed_roles": ["example-role"]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/tokenization/example-transformation/import

Import key version for tokenization transformation

This endpoint imports new key material into an existing tokenization transformation with an imported key.

Method	Path
`POST`	`/transform/transformations/tokenization/:name/import_version`

Note: Transformations whose key material was generated by Vault do not support importing key material. Only transformations that were created through the import endpoint can import new key material from an external source.

Parameters

name (string: <required>) – Specifies the name of the transformation 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 Vault 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.
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.

Sample payload

{
  "ciphertext": "...",
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/transformations/tokenization/example-transformation/import_version

Get wrapping key

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

Method	Path
`GET`	`/transform/wrapping_key`

Sample request

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

Sample response

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

Read transformation

This endpoint queries an existing transformation by the given name.

Method	Path
`GET`	`/transform/transformation/:name`

name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/transformation/example-transformation

Sample response

{
  "data": {
    "allowed_roles": ["example-role"],
    "templates": ["builtin/creditcardnumber"],
    "tweak_source": "internal",
    "type": "fpe"
  }
}

List transformation

This endpoint lists all existing transformations in the secrets engine.

Method	Path
`LIST`	`/transform/transformation`

Sample request

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

Sample response

{
  "data": {
    "keys": ["example-transformation"]
  }
}

Delete transformation

This endpoint deletes an existing transformation by the given name.

Method	Path
`DELETE`	`/transform/transformation/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transform/transformation/example-transformation

Create/Update template

This endpoint creates or updates a template with the given name. If a template with the name does not exist, it will be created. If the template exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/template/:name`

Parameters

name (string: <required>) – Specifies the name of the template to create. This is part of the request URL.
type (string: <required>) - Specifies the type of pattern matching to perform. The only type currently supported by this backend is regex.
pattern (string: <required>) - Specifies the pattern used to match a particular value. For regex type matching, capture group determines the set of character that should be matched against. Any matches outside of capture groups are retained post-transformation.
alphabet (string) - Specifies the name of the alphabet to use when this template is used for FPE encoding and decoding operations.
encode_format (string: "") - The regular expression template to use to format encoded values. This can be used to normalize the encoded output. If absent or empty, encoded values will preserve the format of the input value. This is only used during FPE transformations.
decode_formats (key-value-map: {}) - An optional map of regular expression templates that can be used to customize decoded output. For example, this can be used to decode only the last four digits of a credit card number. This is only used during FPE transformations.

Sample payload

{
  "type": "regex",
  "alphabet": "builtin/numeric",
  "pattern": "(\\d{3})[-/](\\d{2})[-/](\\d{4})",
  "encode_format": "$1-$2-$3",
  "decode_formats": {
    "first-three": "$1",
    "last-four": "$3"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/template/example-template

Read template

This endpoint queries an existing template by the given name.

Method	Path
`GET`	`/transform/template/:name`

name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/template/example-template

Sample response

{
  "data": {
    "alphabet": "builtin/numeric",
    "decode_formats": {
      "first-three": "$1",
      "last-four": "$3"
    },
    "encode_format": "$1-$2-$3",
    "pattern": "(\\d{3})[-/](\\d{2})[-/](\\d{4})",
    "type": "regex"
  }
}

List template

This endpoint lists all existing templates in the secrets engine.

Method	Path
`LIST`	`/transform/template`

Sample request

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

Sample response

{
  "data": {
    "keys": ["example-template"]
  }
}

Delete template

This endpoint deletes an existing template by the given name.

Method	Path
`DELETE`	`/transform/template/:name`

Parameters

name (string: <required>) – Specifies the name of the template to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transform/template/example-template

Create/Update alphabet

This endpoint creates or updates an alphabet with the given name. If an alphabet with the name does not exist, it will be created. If the alphabet exists, it will be updated with the new attributes.

Method	Path
`POST`	`/transform/alphabet/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to create. This is part of the request URL.
alphabet (string: <required>) – Specifies the set of characters that can exist within the provided value and the encoded or decoded value for a FPE transformation.

Sample payload

{
  "alphabet": "abc"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/alphabet/example-alphabet

Read alphabet

This endpoint queries an existing alphabet by the given name.

Method	Path
`GET`	`/transform/alphabet/:name`

name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/alphabet/example-alphabet

Sample response

{
  "data": {
    "alphabet": "abc"
  }
}

List alphabets

This endpoint lists all existing alphabets in the secrets engine.

Method	Path
`LIST`	`/transform/alphabet`

Sample request

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

Sample response

{
  "data": {
    "keys": ["example-alphabet"]
  }
}

Delete alphabet

This endpoint deletes an existing alphabet by the given name.

Method	Path
`DELETE`	`/transform/alphabet/:name`

Parameters

name (string: <required>) – Specifies the name of the alphabet to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transform/alphabet/example-alphabet

Create/Update tokenization store

This endpoint creates or updates a storage configuration for use with tokenization. The database user configured here should only have permission to SELECT, INSERT, and UPDATE rows in the tables.

Method	Path
`POST`	`/transform/stores/:name`

Parameters

name (string: <required>) – Specifies the name of the store to create or update. This is part of the request URL.
type (string: <required>) - Specifies the type of store. Currently only sql is supported.
driver (string: <required>) - Specifies the database driver to use, and thus which SQL database type. Currently the supported options are postgres, mysql, and mssql.
connection_string (string: <required>) - A database connection string with template slots for username and password that Vault will use for locating and connecting to a database. Each database driver type has a different syntax for its connection strings.
When using MySQL, make sure to append ?parseTime=true to enable timestamp parsing.
username: (string: <required>) - The username value to use when connecting to the database.
password: (string: <required>) - The password value to use when connecting to the database.
supported_transformations: (list: ["tokenization"]) The types of transformations this store can host. Currently onlytokenization` is supported.
schema: (string: "public") - The schema within the database to expect tokenization state tables.
max_open_connections (int: 4) - The maximum number of connections to the database at any given time.
max_idle_connections (int: 4) - The maximum number of idle connections to the database at any given time.
max_connection_lifetime (duration: 0) - The maximum amount of time a connection can be open before closing it. 0 means no limit. Uses duration format strings.

Sample payloads

{
  "type": "sql",
  "driver": "postgres",
  "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens",
  "username": "vault_user",
  "password": "very_secret"
}

{
  "type": "sql",
  "driver": "mysql"
  "connection_string": "{{username}}:{{password}}@tcp(mydb.conhugeco.com:3306)/tokens",
  "username": "vault_user",
  "password": "very_secret"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/stores/example-store

Create/Update store schema

This endpoint creates or updates the underlying schema in an SQL type tokenization store. The provided username and password are only used during this call. This is so one may use a user with DDL privileges to create or update the schema, but still use a much more limited user for ordinary operation.

Method	Path
`POST`	`/transform/stores/:name/schema`

Parameters

name (string: <required>) – Specifies the name of the store to create or update. This is part of the request URL.
username: (string: <required>) - The username value to use when connecting to the database.
password: (string: <required>) - The password value to use when connecting to the database.
transformation_type: (string: "tokenization") - The transformation type. Currently only tokenization is supported.

Sample payload

{
  "username": "ddl_user",
  "password": "very_secret"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/transform/stores/example-store/schema

Read store

This endpoint queries an existing store by the given name.

Method	Path
`GET`	`/transform/stores/:name`

name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/stores/example-store

Sample response

{
  "data": {
    "type": "sql",
    "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens",
    "supported_transformations": ["tokenization"]
  }
}

List stores

This endpoint lists all existing stores in the secrets engine.

Method	Path
`LIST`	`/transform/stores`

Sample request

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

Sample response

{
  "data": {
    "keys": ["example-store"]
  }
}

Delete store

This endpoint deletes an existing store configuration by the given name.

Method	Path
`DELETE`	`/transform/stores/:name`

Parameters

name (string: <required>) – Specifies the name of the store to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/transform/stores/example-store

Encode

This endpoint encodes the provided value using a named role.

Method	Path
`POST`	`/transform/encode/:role_name`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the value to be encoded.
transformation (string) – Specifies the transformation within the role that should be used for this encode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
expiration (string: "") - Only applicable for tokenization transforms. Either ttl or expiration may be configured but not both at the same time. Capped to the role's max_ttl value if that's set. When omitted the tokenization transforms shall never expire. The provided string must be a RFC3339 formatted time and date.
ttl (duration "0") - Specifies the TTL of the resulting token. Only applicable for tokenization transformations.
metadata (string) - For tokenization transforms, a list of key value pairs of the form key1=value1,key2=value2,... These optional metadata values will be stored with the value and can be retrieved with the metadata endpoint.
tweak (string) – Specifies the base64 encoded tweak to use. Only applicable for FPE transformations with supplied as the tweak source. The tweak must be a 7-byte value that is then base64 encoded.
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 encoded in a single batch. When this parameter is set, the 'value', 'transformation', 'ttl', 'tweak' and 'reference' parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list.

[
  {
    "value": "1111-1111-1111-1111",
    "transformation": "ccn-fpe"
  },
  {
    "value": "2222-2222-2222-2222",
    "transformation": "ccn-masking",
    "reference": "order#1234"
  },
  {
    "value": "3333-3333-3333-3333",
    "transformation": "ccn-tokenization",
    "ttl": "42d"
  }
]

NOTE: The response payload may return a tweak along with the encoded value if the tweak_source for the specified transformation is set to generated. The resource owner should properly store this tweak, which must be supplied back when decrypting the encoded value.

Sample payload

{
  "value": "1111-2222-3333-4444",
  "transformation": "ccn-fpe"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/encode/example-role

Sample response

{
  "data": {
    "encoded_value": "5682-4613-6822-8064"
  }
}

Sample payload

{
  "batch_input": [
    {
      "transformation": "ccn-fpe",
      "value": "1111-2222-3333-4444"
    },
    {
      "transformation": "ccn-tokenization",
      "value": "1111-2222-3333-4444",
      "reference": "order#1234"
    }
  ]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/encode/example-role

Sample response

{
  "data": {
    "batch_results": [
      {
        "encoded_value": "5682-4613-6822-8064"
      },
      {
        "encoded_value": "Q4tYgFXHxURXf9MLekG82L51vSAQrDnpAiaB37J4VPRxoQEB3fRpwR",
        "reference": "order#1234"
      }
    ]
  }
}

Decode

This endpoint decodes the provided value using a named role.

Method	Path
`POST`	`/transform/decode/:role_name(/:decode_format)`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the value to be decoded.
decode_format (string) - The name of the decode format to use for decoding. These are defined in decode_formats when creating the transformation's template, and can be used to selectively decode or format the output. If one is not defined or specified, the template's pattern will be used. Only applicable for FPE transformations.
transformation (string) – Specifies the transformation within the role that should be used for this decode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
tweak (string) – Specifies the base64 encoded tweak to use. Only applicable for FPE transformations with supplied or generated as the tweak source. The tweak must be a 7-byte value that is then base64 encoded.
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 decoded in a single batch. When this parameter is set, the 'value', 'transformation', 'tweak' and 'reference' parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list.
```
[
  {
    "value": "5682-4613-6822-8064",
    "transformation": "ccn-fpe"
  }
]
```

Sample payload

{
  "value": "418-56-4374",
  "transformation": "example-transformation"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/decode/example-role

Sample response

{
  "data": {
    "decoded_value": "111-22-3333"
  }
}

Sample payload

{
  "value": "418-56-4374",
  "transformation": "example-transformation"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/decode/example-role/last-four

Sample response

{
  "data": {
    "decoded_value": "4444"
  }
}

Sample payload

{
  "batch_input": [
    {
      "transformation": "ccn-fpe",
      "value": "5682-4613-6822-8064",
      "reference": "order#1234"
    },
    {
      "transformation": "ccn-tokenization",
      "value": "Q4tYgFXHxURXf9MLekG82L51vSAQrDnpAiaB37J4VPRxoQEB3fRpwR"
    }
  ]
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/decode/example-role

Sample response

{
  "data": {
    "batch_results": [
      {
        "encoded_value": "1111-2222-3333-4444",
        "reference": "order#1234"
      },
      {
        "encoded_value": "1111-2222-3333-4444"
      }
    ]
  }
}

Validate token

This endpoint determines if a provided tokenized value is valid and unexpired. Only valid for tokenization transformations.

Method	Path
`POST`	`/transform/validate/:role_name`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the token for which to check validity.
transformation (string) – Specifies the transformation within the role that should be used for this decode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
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 validated in a single batch. When this parameter is set, the 'value', 'transformation' and 'reference' parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list.
```
[
  {
    "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
    "transformation": "ccn-tokenization"
  }
]
```

Sample payload

{
  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
  "transformation": "ccn-tokenization"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/validate/example-role

Sample response

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

Check tokenization

This endpoint determines if a provided plaintext value has an valid, unexpired tokenized value. Note that this cannot return the token, just confirm that a tokenized value exists, but works for all tokenization modes. This endpoint is only valid for tokenization transformations.

Method	Path
`POST`	`/transform/tokenized/:role_name`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the token to plaintext for which to check whether it has been tokenized.
transformation (string) – Specifies the transformation within the role that should be used for this decode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
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 decoded in a single batch. When this parameter is set, the 'value', 'transformation', and 'reference' parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list. In addition, batched requests can add the 'reference' field described above.
```
[
  {
    "value": "1111-1111-1111-1111",
    "transformation": "ccn-tokenization"
  }
]
```

Sample payload

{
  "value": "1111-1111-1111-1111",
  "transformation": "ccn-tokenization"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/tokenized/example-role

Sample response

{
  "data": {
    "tokenized": true
  }
}

Lookup token

This endpoint returns the token given a plaintext and optionally an expiration or range of expirations. This operation is only supported if the transformation is configured as 'convergent', or if the mapping mode is exportable and the storage backend is external. Tokens may be looked up with an explicit expiration, an expiration value of "any", or with a range of acceptable expiration times. This endpoint is only valid for tokenization transformations.

Method	Path
`POST`	`/transform/tokens/:role_name`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the token to test for whether it has a valid tokenization.
expiration (string: "") - The precise expiration of the token. If omitted, this specifically searches for tokens with no expiration. If the string "any", will return tokens with any or no expiration. Otherwise, the string must be the RFC3339 formatted time and date of expiration. expiration may not be used at the same time as min_expiration and max_expiration.
min_expiration (string: "") - The minimum expiration time of the token, inclusive, as an RFC3339 formatted time and date. min_expiration may not be used at the same time as expiration. When provided, max_expiration must also be provided.
max_expiration (string: "") - The maximum expiration time of the token, inclusive, as an RFC3339 formatted time and date. max_expiration may not be used at the same time as expiration. When provided, min_expiration must also be provided.
transformation (string) – Specifies the transformation within the role that should be used for this lookup operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
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 decoded in a single batch. When this parameter is set, the value, transformation, and reference parameters are ignored. Instead, the aforementioned parameters should be provided within each object in the list. In addition, batched requests can add the reference field described above.
```
[
  {
    "value": "1111-1111-1111-1111",
    "expiration": "any",
    "transformation": "ccn-tokenization"
  }
]
```

Sample payload

{
  "value": "1111-1111-1111-1111",
  "min_expiration": "2022-06-06T3:14:15+00:00",
  "min_expiration": "2022-06-07T9:26:53+00:00",
  "transformation": "ccn-tokenization"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/tokens/example-role

Sample response

{
  "data": {
    "tokens": [
      "AHLdmFvTRknMBgrNSy6Ba7xJxG28KkZeHKqxGJ7e45G3V9UbcUr6gdv83ozwRRQwLfJgyHZvfa9rh7kU9xJXVdY"
    ]
  }
}

Retrieve token metadata

This endpoint retrieves metadata for a tokenized value using a named role. Only valid for tokenization transformations.

Method	Path
`POST`	`/transform/metadata/:role_name`

Parameters

role_name (string: <required>) – Specifies the role name to use for this operation. This is specified as part of the URL.
value (string: <required>) – Specifies the token for which to retrieve metadata.
transformation (string) – Specifies the transformation within the role that should be used for this decode operation. If a single transformation exists for role, this parameter may be skipped and will be inferred. If multiple transformations exist, one must be specified.
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 decoded in a single batch. When this parameter is set, the 'value' parameter is ignored. Instead, the aforementioned parameters should be provided within each object in the list. In addition, batched requests can add the 'reference' field described above.
```
[
  {
    "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
    "transformation": "ccn-tokenization"
  }
]
```

Sample payload

{
  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
  "transformation": "ccn-tokenization"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/encode/example-role

Sample response

{
  "data": {
    "metadata": "Department=Marketing"
    "expiration_time": "2020-11-04T04:00:00+00:00",
  }
}

Snapshot tokenization state

This endpoint starts or continues retrieving a snapshot of the stored state of a tokenization transform. This state is protected as it is in the underlying store, and so is safe for storage or transport. Snapshots may be used for backup purposes or to migrate from one store to another. If more than one store is configured for a tokenization transform, the snapshot data contains the contents of the first store.

Since more values may exist than can be returned in a single call, if a snapshot has more values, the response will contain the continuation field, an opaque value that if provided on a subsequent call will resume snapshotting at the next value. If absent, the end of the snapshot has been reached.

Snapshots are guaranteed to contain the values present at the time of the first call to start the snapshot. Values tokenized after the snapshot began may or may not be included.

Method	Path
`POST`	`/transform/transformations/tokenization/snapshot/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to snapshot.
limit (int: 1000) - The maximum number of tokenized value states to return on this call.
continuation string: "" - If absent or empty, a new snapshot is started. If present, the snapshot should continue at the next available value.

Sample payload

{
  "limit": 3,
  "continuation": "2F1nUpUKMZUBnwQ77qByt1"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1//transform/transformations/tokenization/snapshot/sample-transform

Sample response

{
  "data": {
    "continuation": "2F1nUpUKMZUBnwQ77qBt4D",
    "values": [
      "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==",
      "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==",
      "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg=="
    ]
  }
}

Restore tokenization state

This endpoint restores previously snapshotted tokenization state values to the underlying store(s) of a tokenization transform. Calls to this endpoint are idempotent, so multiple outputs from a snapshot run can be applied via restore in any order and duplicates will not cause a problem.

Values snapshotted from a default mapping mode store cannot be restored into an exportable mode store and vice versa.

Method	Path
`POST`	`/transform/transformations/tokenization/restore/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to restore.
values ([]string: <required>) - Any number of tokenization state values from a previous snapshot call.

Sample payload

{
  "values": [
    "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==",
    "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==",
    "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg=="
  ]
}

Sample request

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

Export decoded tokenization state

This endpoint starts or continues retrieving an export of tokenization state, including the tokens and their decoded values. This call is only supported on tokenization stores configured with the exportable mapping mode. Refer to the Tokenization documentation for when to use the exportable mapping mode. Decoded values are in Base64 representation.

Since more values may exist than can be returned in a single call, if an export has more values, the response will contain the continuation field, an opaque value that if provided on a subsequent call will resume snapshotting at the next value. If absent, the end of the export has been reached.

Exports are guaranteed to contain the values present at the time of the first call to start the export. Values tokenized after the snapshot began may or may not be included.

Method	Path
`POST`	`/transform/transformations/tokenization/export-decoded/:name`

Parameters

name (string: <required>) – Specifies the name of the transformation to export.
limit (int: 1000) - The maximum number of tokenized value states to return on this call.
continuation string: "" - If absent or empty, a new export is started. If present, the export should continue at the next available value.

Sample payload

{
  "limit": 3,
  "continuation": "2F1nUpUKMZUBnwQ77qByt1"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1//transform/transformations/tokenization/export-decoded/sample-transform

Sample response

{
  "data": {
    "continuation": "4hELrrmGAwhHFjmMFny",
    "values": [
      {
        "plaintext": "dmFsdWUtMA==",
        "token": "Q4tYgFXHxUaPhDdV9rx2CduZGPxjYpAp1K523AUsNM5A2Z6DrXj3zz"
      },
      {
        "plaintext": "dmFsdWUtMg==",
        "token": "Q4tYgFXHxUNyMfqRW6fA82DYvMigwdf6JjATauyVzqx2SsmUShMhN5",
        "expiration_time": "2021-03-15T00:31:10Z"
      },
      {
        "plaintext": "dmFsdWUtMQ==",
        "token": "Q4tYgFXHxUNtW27owABRv5GjuxjXTCGebPr7xkqRAY18YVmfZsk2MV"
      }
    ]
  }
}

Rotate tokenization key

This endpoint rotates the version of the named key. After rotation, new requests will be encoded with the new version of the key.

Method	Path
`POST`	`/transform/tokenization/keys/:transform_name/rotate`

Parameters

transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transform/tokenization/keys/transform_name/rotate

Update tokenization key config

This endpoint allows the minimum key version to be set for decode operations. Only valid for tokenization transformations.

Method	Path
`POST`	`/transform/tokenization/keys/:transform_name/config`

Parameters

transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.
min_decryption_version (int: <optional>) – Specifies the minimum key version that vault can use to decode values for the corresponding transform.
auto_rotate_period (duration: "0", 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. Uses duration format strings.

Sample payload

[
  {
    "min_decryption_version": 1,
    "auto_rotate_period": "4320h"
  }
]

Sample request

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

List tokenization key configuration

List all tokenization keys. Only valid for tokenization transformations.

Method	Path
`LIST`	`/transform/tokenization/keys/`

Sample request

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

Read tokenization key configuration

Read tokenization key configuration for a particular transform. Only valid for tokenization transformations.

Method	Path
`GET`	`/transform/tokenization/keys/:transform_name`

Parameters

transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/transform/tokenization/keys/:transform_name

Sample response

{
  "data": {
    "latest_version": 1,
    "min_available_version": 0,
    "min_decryption_version": 1,
    "auto_rotate_period": "4320h",
    "name": "transform_name"
  }
}

Trim tokenization key version

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`	`/transform/tokenization/keys/:transform_name/trim`

Parameters

transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.
min_available_version (int: <required>) – Specifies minimum key version available for use for this transform. All versions below this will be permanently forgotten. Cannot be set below min_decryption_version or above latest_version.

Sample payload

{
  "min_available_version": 1
}

Sample request

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

Transform secrets engine (API)

Create/Update role

Parameters

Sample payload

Sample request

Read role

Parameters

Sample request

Sample response

List roles

Parameters

Sample request

Sample response

Delete role

Parameters

Sample request

Create/Update transformation DEPRECATED (1.6)

Parameters

Sample payload

Sample request

Create/Update FPE transformation

Parameters

Sample payload

Sample request

Create/Update masking transformation

Parameters

Sample payload

Sample request

Create/Update tokenization transformation

Parameters

Sample payload

Sample request

Import key for FPE transformation

Parameters

Sample payload

Sample request

Import key for tokenization transformation

Parameters

Sample payload

Sample request

Import key version for tokenization transformation

Parameters

Sample payload

Sample request

Get wrapping key

Sample request

Sample response

Read transformation

Sample request

Sample response

List transformation

Sample request

Sample response

Delete transformation

Parameters

Sample request

Create/Update template

Parameters

Sample payload

Sample request

Read template

Sample request

Sample response

List template

Sample request

Sample response

Delete template

Parameters

Sample request

Create/Update alphabet

Parameters

Sample payload

Sample request

Read alphabet

Sample request

Sample response

List alphabets

Sample request

Sample response

Delete alphabet

Create/Update transformation ^{DEPRECATED (1.6)}