Transform Secrets Engine (API)

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

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

Create/Update Role

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

Parameters

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

• transformations (list: []) - Specifies the transformations that can be used with this role.

Sample Payload

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

Sample Request

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

Read Role

This endpoint queries an existing role by the given name.

Parameters

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

Sample Request

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

Sample Response

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

List Roles

This endpoint lists all existing roles in the secrets engine.

Sample Request

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

Sample Response

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

Delete Role

This endpoint deletes an existing role by the given name.

Parameters

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

Sample Request

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

Create/Update Transformation

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.

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

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

Sample Request

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

Read Transformation

This endpoint queries an existing transformation by the given name.

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

Sample Request

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

Sample Response

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

List Transformation

This endpoint lists all existing transformations in the secrets engine.

Sample Request

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

Sample Response

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

Delete Transformation

This endpoint deletes an existing transformation by the given name.

Parameters

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

Sample Request

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

Create/Update Template

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

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

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

Sample Request

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

Read Template

This endpoint queries an existing template by the given name.

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

Sample Request

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

Sample Response

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

List Template

This endpoint lists all existing templates in the secrets engine.

Sample Request

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

Sample Response

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

Delete Template

This endpoint deletes an existing template by the given name.

Parameters

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

Sample Request

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

Create/Update Alphabet

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

Parameters

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

• alphabet (string: <required>) – Specifies the set of characters that can exist within the provided value and the encoded or decoded value for a FPE transformation.

Sample Payload

{
  "alphabet": "abc"
}

Sample Request

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

Read Alphabet

This endpoint queries an existing alphabet by the given name.

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

Sample Request

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

Sample Response

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

List Alphabets

This endpoint lists all existing alphabets in the secrets engine.

Sample Request

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

Sample Response

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

Delete Alphabet

This endpoint deletes an existing alphabet by the given name.

Parameters

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

Sample Request

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

Encode

This endpoint encodes the provided value using a named role.

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.

  [
    {
      "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

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

Sample Request

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

Sample Response

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

Decode

This endpoint decodes the provided value using a named role.

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.

  [
    {
      "value": "5682-4613-6822-8064",
      "transformation": "ccn-fpe"
    }
  ]
  

Sample Payload

{
  "value": "5682-4613-6822-8064",
  "transformation": "ccn-fpe"
}

Sample Request

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

Sample Response

{
  "data": {
    "decoded_value": "1111-2222-3333-4444"
  }
}