open-vault/website/content/api-docs/secret/transform.mdx

---
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: <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

```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: <required>)` –
  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: <required>)` –
  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 <sup>DEPRECATED (1.6)</sup>

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

-

### 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: <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.

### 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: <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

```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: <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.

- `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: <required>)` –
  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: <required>)` –
  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: <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

```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: <required>)` –
  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: <required>)` –
  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: <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

```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: <required>)` –
  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: <required>)` –
  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/store/: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` or `mysql`

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

### 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/store/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/store/: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

```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/store/example-store/schema
```

## Read Store

This endpoint queries an existing store by the given name.

| Method | Path                     |
| :----- | :----------------------- |
| `GET`  | `/transform/store/:name` |

- `name` `(string: <required>)` –
  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/store/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/store` |

### 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/store/:name` |

### Parameters

- `name` `(string: <required>)` –
  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/store/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.

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

  ```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: <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.

  ```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: <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.

  ```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. 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 test for whether it has a valid tokenization.

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

  ```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
  }
}
```

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

  ```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: <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

```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: <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

```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: <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

```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: <required>)` –
  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: <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.

### Sample Payload

```json
[
  {
    "min_decryption_version": 1
  }
]
```

### 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: <required>)` –
  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,
    "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

```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
```