--- layout: api page_title: Transform - Secrets Engines - HTTP API description: This is the API documentation for the Transform secrets engine. --- # 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](/docs/secrets/transform). 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: )` – 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 ```json { "transformations": ["creditcard-fpe", "creditcard-masking"] } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the role to read. This is part of the request URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/transform/role/example-role ``` ### Sample Response ```json { "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 ```shell-session $ curl --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/transform/role ``` ### Sample Response ```json { "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: )` – Specifies the name of the role to delete. This is part of the request URL. ### Sample Request ```shell-session $ 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. - [FPE](#create-update-fpe-transformation) - [Masking](#create-update-masking-transformation) - [Tokenization](#create-update-tokenization-transformation) | Method | Path | | :----- | :-------------------------------- | | `POST` | `/transform/transformation/:name` | ### Parameters - `name` `(string: )` – Specifies the name of the transformation to create or update. This is part of the request URL. - `type` `(string: )` - 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: )` - 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. - ### Sample Payload ```json { "type": "fpe", "template": "builtin/creditcardnumber", "tweak_source": "internal", "allowed_roles": ["example-role"] } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the transformation to create or update. This is part of the request URL. - `template` `(string: )` - 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. ### Sample Payload ```json { "template": "builtin/creditcardnumber", "tweak_source": "internal", "allowed_roles": ["example-role"] } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the transformation to create or update. This is part of the request URL. - `template` `(string: )` - 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 ```json { "template": "builtin/creditcardnumber", "masking_character": "X", "allowed_roles": ["example-role"] } ``` ### Sample Request ```shell-session $ 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: )` – 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. - `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 ```json { "max_ttl": "365d", "allowed_roles": ["example-role"] } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ https://127.0.0.1:8200/v1/transform/transformations/tokenization/example-transformation ``` ## Read Transformation This endpoint queries an existing transformation by the given name. | Method | Path | | :----- | :--------------------------------- | | `GET` | `/transform/transformation/:name` | - `name` `(string: )` – Specifies the name of the role to read. This is part of the request URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/transform/transformation/example-transformation ``` ### Sample Response ```json { "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 ```shell-session $ curl --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/transform/transformation ``` ### Sample Response ```json { "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: )` – Specifies the name of the transformation to delete. This is part of the request URL. ### Sample Request ```shell-session $ 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: )` – Specifies the name of the template to create. This is part of the request URL. - `type` `(string: )` - Specifies the type of pattern matching to perform. The only type currently supported by this backend is `regex`. - `pattern` `(string: )` - 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 ```json { "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 ```shell-session $ 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: )` – Specifies the name of the role to read. This is part of the request URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/transform/template/example-template ``` ### Sample Response ```json { "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 ```shell-session $ curl --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/transform/template ``` ### Sample Response ```json { "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: )` – Specifies the name of the template to delete. This is part of the request URL. ### Sample Request ```shell-session $ 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: )` – Specifies the name of the transformation to create. This is part of the request URL. - `alphabet` `(string: )` – Specifies the set of characters that can exist within the provided value and the encoded or decoded value for a FPE transformation. ### Sample Payload ```json { "alphabet": "abc" } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the role to read. This is part of the request URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/transform/alphabet/example-alphabet ``` ### Sample Response ```json { "data": { "alphabet": "abc" } } ``` ## List Alphabets This endpoint lists all existing alphabets in the secrets engine. | Method | Path | | :----- | :-------------------- | | `LIST` | `/transform/alphabet` | ### Sample Request ```shell-session $ curl --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/transform/alphabet ``` ### Sample Response ```json { "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: )` – Specifies the name of the alphabet to delete. This is part of the request URL. ### Sample Request ```shell-session $ 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: )` – Specifies the name of the store to create or update. This is part of the request URL. - `type` `(string: )` - Specifies the type of store. Currently only `sql` is supported. - `driver` `(string: )` - Specifies the database driver to use, and thus which SQL database type. Currently the supported options are `postgres` or `mysql` - `connection_string` `(string: )` - 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: )` - The username value to use when connecting to the database. - `password`: `(string: )` - The password value to use when connecting to the database. - `supported_transformations: `(list: ["tokenization"])` The types of transformations this store can host. Currently only`tokenization` 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](/docs/concepts/duration-format). ### Sample Payloads ```json { "type": "sql", "driver": "postgres", "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens", "username": "vault_user", "password": "very_secret" } ``` ```json { "type": "sql", "driver": "mysql" "connection_string": "{{username}}:{{password}}@tcp(mydb.conhugeco.com:3306)/tokens", "username": "vault_user", "password": "very_secret" } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the store to create or update. This is part of the request URL. - `username`: `(string: )` - The username value to use when connecting to the database. - `password`: `(string: )` - The password value to use when connecting to the database. - `transformation_type`: `(string: "tokenization")` - The transformation type. Currently only `tokenization` is supported. ### Sample Payload ```json { "username": "ddl_user", "password": "very_secret" } ``` ### Sample Request ```shell-session $ 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: )` – Specifies the name of the role to read. This is part of the request URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/transform/stores/example-store ``` ### Sample Response ```json { "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 ```shell-session $ curl --header "X-Vault-Token: ..." \ --request LIST \ http://127.0.0.1:8200/v1/transform/store ``` ### Sample Response ```json { "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: )` – Specifies the name of the store to delete. This is part of the request URL. ### Sample Request ```shell-session $ 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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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. - `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](#retrieve-token-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: 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. ```json [ { "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 ```json { "value": "1111-2222-3333-4444", "transformation": "ccn-fpe" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/encode/example-role ``` ### Sample Response ```json { "data": { "encoded_value": "5682-4613-6822-8064" } } ``` ### Sample Payload ```json { "batch_input": [ { "transformation": "ccn-fpe", "value": "1111-2222-3333-4444" }, { "transformation": "ccn-tokenization", "value": "1111-2222-3333-4444", "reference": "order#1234" } ] } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/encode/example-role ``` ### Sample Response ```json { "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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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: 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. ```json [ { "value": "5682-4613-6822-8064", "transformation": "ccn-fpe" } ] ``` ### Sample Payload ```json { "value": "418-56-4374", "transformation": "example-transformation" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/decode/example-role ``` ### Sample Response ```json { "data": { "decoded_value": "111-22-3333" } } ``` ### Sample Payload ```json { "value": "418-56-4374", "transformation": "example-transformation" } ``` ### Sample Request ```shell-session $ 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 ```json { "data": { "decoded_value": "4444" } } ``` ### Sample Payload ```json { "batch_input": [ { "transformation": "ccn-fpe", "value": "5682-4613-6822-8064", "reference": "order#1234" }, { "transformation": "ccn-tokenization", "value": "Q4tYgFXHxURXf9MLekG82L51vSAQrDnpAiaB37J4VPRxoQEB3fRpwR" } ] } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/decode/example-role ``` ### Sample Response ```json { "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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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: 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. ```json [ { "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0", "transformation": "ccn-tokenization" } ] ``` ### Sample Payload ```json { "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0", "transformation": "ccn-tokenization" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/validate/example-role ``` ### Sample Response ```json { "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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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: 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. ```json [ { "value": "1111-1111-1111-1111", "transformation": "ccn-tokenization" } ] ``` ### Sample Payload ```json { "value": "1111-1111-1111-1111", "transformation": "ccn-tokenization" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/tokenized/example-role ``` ### Sample Response ```json { "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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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: 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. ```json [ { "value": "1111-1111-1111-1111", "expiration": "any", "transformation": "ccn-tokenization" } ] ``` ### Sample Payload ```json { "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 ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/tokens/example-role ``` ### Sample Response ```json { "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: )` – Specifies the role name to use for this operation. This is specified as part of the URL. - `value` `(string: )` – 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: 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. ```json [ { "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0", "transformation": "ccn-tokenization" } ] ``` ### Sample Payload ```json { "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0", "transformation": "ccn-tokenization" } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/encode/example-role ``` ### Sample Response ```json { "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: )` – 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 ```json { "limit": 3, "continuation": "2F1nUpUKMZUBnwQ77qByt1" } ``` ### Sample Request ```shell-session $ 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 ```json { "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: )` – Specifies the name of the transformation to restore. - `values` `([]string: )` - Any number of tokenization state values from a previous snapshot call. ### Sample Payload ```json { "values": [ "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==", "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==", "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg==" ] } ``` ### Sample Request ```shell-session $ 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](../../docs/secrets/transform/tokenization#security-considerations) 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: )` – 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 ```json { "limit": 3, "continuation": "2F1nUpUKMZUBnwQ77qByt1" } ``` ### Sample Request ```shell-session $ 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 ```json { "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: )` – Specifies the transform name to use for this operation. This is specified as part of the URL. ### Sample Request ```shell-session $ 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: )` – Specifies the transform name to use for this operation. This is specified as part of the URL. - `min_decryption_version` `(int: )` – 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](/docs/concepts/duration-format). ### Sample Payload ```json [ { "min_decryption_version": 1, "auto_rotate_period": "4320h" } ] ``` ### Sample Request ```shell-session $ 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 ```shell-session $ 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: )` – Specifies the transform name to use for this operation. This is specified as part of the URL. ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform/tokenization/keys/:transform_name ``` ### Sample Response ```json { "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: )` – Specifies the transform name to use for this operation. This is specified as part of the URL. - `min_available_version` `(int: )` – 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 ```json { "min_available_version": 1 } ``` ### Sample Request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request LIST \ --data @payload.json \ http://127.0.0.1:8200/v1/transform//transform/tokenization/keys/:transform_name/trim ```