open-vault/website/pages/api-docs/secret/transform/index.mdx

---
layout: api
page_title: Transform - Secrets Engines - HTTP API
sidebar_title: Transform <sup>ENTERPRISE</sup>
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/transformation/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/transformation/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/transformation/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/transformation/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/transformation/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/transformation/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 ony 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.

### Sample Payload

```json
{
  "type": "regex",
  "pattern": "(\\d{9})",
  "alphabet": "builtin/numeric"
}
```

### 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",
    "pattern": "(\\d{9})",
    "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.

- `supported_transformations: `(list: ["tokenization"])` 
  The types of transformations this store can host.  Currently only `tokenization`
  is supported.

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

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


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

```json
{
  "type": "sql",
  "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/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.

- `transformation_type`: `(string: "tokenization")` -
  The transformation type.  Currently only tokenization is supported.

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


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

- `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' and 'tweak' 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"
    },
    { "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"
     }
  ]
}
```

### 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"
      },
    ]
  }
}
```

## Decode

This endpoint decodes the provided value using a named role.

| Method | Path                           |
| :----- | :----------------------------- |
| `POST` | `/transform/decode/: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 decoded.

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

- `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 'tweak' 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": "5682-4613-6822-8064",
  "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": {
    "decoded_value": "1111-2222-3333-4444"
  }
}
```

### Sample Payload

```json
{
  "batch_input": [
     {
      "transformation": "ccn-fpe",
      "value": "5682-4613-6822-8064"
     }, 
     {
      "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"
      },
      {
        "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.

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

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

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

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

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

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