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

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.

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

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

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

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

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

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

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