»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"]
}

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

$ 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

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

»Sample Response

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

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

»List Roles

This endpoint lists all existing roles in the secrets engine.

»Parameters

• filter (string: "*") – If provided, only returns role names that match the given glob.

»Sample Request

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

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

»Sample Response

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

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

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

»Create/Update Transformation ^{DEPRECATED (1.6)}

This endpoint creates or updates a transformation with the given name. If a transformation with the name does not exist, it will be created. If the transformation exists, it will be updated with the new attributes. This endpoint is deprecated as of version 1.6 in favor of the type specific configuration endpoints, and will be removed in a future release.

• FPE
• Masking
• Tokenization

»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

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

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

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

»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

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

{  "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/transformations/fpe/example-transformation

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

»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

{
  "template": "builtin/creditcardnumber",
  "masking_character": "X",
  "allowed_roles": ["example-role"]
}

{  "template": "builtin/creditcardnumber",  "masking_character": "X",  "allowed_roles": ["example-role"]}

»Sample Request

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

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

»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

{
  "max_ttl": "365d",
  "allowed_roles": ["example-role"]
}

{  "max_ttl": "365d",  "allowed_roles": ["example-role"]}

»Sample Request

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

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

• 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

$ 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"
  }
}

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

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

»Sample Response

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

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

$ 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"
}

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

$ 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

$ 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"
  }
}

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

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

»Sample Response

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

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

$ 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"
}

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

$ 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

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

»Sample Response

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

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

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

»Sample Response

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

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

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

»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

• supported_transformations: (list: ["tokenization"]) The types of transformations this store can host. Currently onlytokenization` 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. 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.

• 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

{
  "type": "sql",
  "driver": "postgres",
  "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens",
  "username": "vault_user",
  "password": "very_secret"
}

{  "type": "sql",  "driver": "postgres",  "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens",  "username": "vault_user",  "password": "very_secret"}

{
  "type": "sql",
  "driver": "mysql"
  "connection_string": "{{username}}:{{password}}@tcp(mydb.conhugeco.com:3306)/tokens",
  "username": "vault_user",
  "password": "very_secret"
}

{  "type": "sql",  "driver": "mysql"  "connection_string": "{{username}}:{{password}}@tcp(mydb.conhugeco.com:3306)/tokens",  "username": "vault_user",  "password": "very_secret"}

»Sample Request

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

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

»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

{
  "username": "ddl_user",
  "password": "very_secret"
}

{  "username": "ddl_user",  "password": "very_secret"}

»Sample Request

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

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

• 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/store/example-store

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

»Sample Response

{
  "data": {
    "type": "sql",
    "connection_string": "postgresql://{{username}}:{{password}}@mydb.conhugeco.com/tokens",
    "supported_transformations": ["tokenization"]
  }
}

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

»Sample Request

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

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

»Sample Response

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

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

»Delete Store

This endpoint deletes an existing store configuration by the given name.

»Parameters

• name (string: <required>) – Specifies the name of the store 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/store/example-store

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

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

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

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

  Copy

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

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

$ 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"
  }
}

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

»Sample Payload

{
  "batch_input": [
    {
      "transformation": "ccn-fpe",
      "value": "1111-2222-3333-4444"
    },
    {
      "transformation": "ccn-tokenization",
      "value": "1111-2222-3333-4444"
    }
  ]
}

{  "batch_input": [    {      "transformation": "ccn-fpe",      "value": "1111-2222-3333-4444"    },    {      "transformation": "ccn-tokenization",      "value": "1111-2222-3333-4444"    }  ]}

»Sample Request

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

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

»Sample Response

{
  "data": {
    "batch_results": [
      {
        "encoded_value": "5682-4613-6822-8064"
      },
      {
        "encoded_value": "Q4tYgFXHxURXf9MLekG82L51vSAQrDnpAiaB37J4VPRxoQEB3fRpwR"
      }
    ]
  }
}

{  "data": {    "batch_results": [      {        "encoded_value": "5682-4613-6822-8064"      },      {        "encoded_value": "Q4tYgFXHxURXf9MLekG82L51vSAQrDnpAiaB37J4VPRxoQEB3fRpwR"      }    ]  }}

»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"
    }
  ]
  

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

  Copy

»Sample Payload

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

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

$ 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"
  }
}

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

»Sample Payload

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

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

»Sample Request

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

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

»Sample Response

{
  "data": {
    "batch_results": [
      {
        "encoded_value": "1111-2222-3333-4444"
      },
      {
        "encoded_value": "1111-2222-3333-4444"
      }
    ]
  }
}

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

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

  [
    {
      "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
      "transformation": "ccn-tokenization"
    }
  ]
  

  [  {    "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",    "transformation": "ccn-tokenization"  }]

  Copy

»Sample Payload

{
  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
  "transformation": "ccn-tokenization"
}

{  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",  "transformation": "ccn-tokenization"}

»Sample Request

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

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

»Sample Response

{
  "data": {
    "valid": true
  }
}

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

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

  [
    {
      "value": "1111-1111-1111-1111",
      "transformation": "ccn-tokenization"
    }
  ]
  

  [  {    "value": "1111-1111-1111-1111",    "transformation": "ccn-tokenization"  }]

  Copy

»Sample Payload

{
  "value": "1111-1111-1111-1111",
  "transformation": "ccn-tokenization"
}

{  "value": "1111-1111-1111-1111",  "transformation": "ccn-tokenization"}

»Sample Request

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

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

»Sample Response

{
  "data": {
    "tokenized": true
  }
}

{  "data": {    "tokenized": true  }}

»Retrieve Token Metadata

This endpoint retrieves metadata for a tokenized value using a named role. Only valid for tokenization transformations.

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

  [
    {
      "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
      "transformation": "ccn-tokenization"
    }
  ]
  

  [  {    "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",    "transformation": "ccn-tokenization"  }]

  Copy

»Sample Payload

{
  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",
  "transformation": "ccn-tokenization"
}

{  "value": "CAESLAoYChAhsIt7Urh6GmN2VnxAeuLGENuF8fkFEhBYz7wwdFyJPrhyDmvZg7L0",  "transformation": "ccn-tokenization"}

»Sample Request

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

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

»Sample Response

{
  "data": {
    "metadata": "Department=Marketing"
    "expiration_time": "2020-11-04T04:00:00+00:00",
  }
}

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

»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

{
  "limit": 3,
  "continuation": "2F1nUpUKMZUBnwQ77qByt1"
}

{  "limit": 3,  "continuation": "2F1nUpUKMZUBnwQ77qByt1"}

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1//transform/transformations/tokenization/snapshot/sample-transform

$ 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

{
  "data": {
    "continuation": "2F1nUpUKMZUBnwQ77qBt4D",
    "values": [
      "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==",
      "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==",
      "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg=="
    ]
  }
}

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

»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

{
  "values": [
    "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==",
    "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==",
    "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg=="
  ]
}

{  "values": [    "CiDiVGJaXlcS0ky4mRVvfLdxk7FWh8ATcFMSbQRtWCs/HxJ8CAESIGQH2oukpwPAFoK2SaKUcYAxrnxtvJn7n5d3dWx2eCLcIkZ3FXcQKu5+Bnl4NzOSL2ZkU5t9OOpQOMg0lwsMkq0Vm98ANGC9RabaP2ePddzTkD58GBvsVetYVnqHQFZufQ2pw/EXkFIWMg4I4KvX4vf/////ARCgHw==",    "CiADFWL7/equiN83oWl/MvYWRYQLvjUxDVvoxK1Ghw4drBJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIka2nyOX1z3D4pMsZWwMFJlNBiT1Lb4MMZ6CUbclykLw/LBG5GTWQbOXx/3Vd54RAA82382mUem8Lu8BCMJYAa6vj/6aS9CLMg4I4KvX4vf/////ARCIJw==",    "CiBf2+RqeiXmIHIh2fytEKOesTZ5U31D4BZ5xyhpuj3UfRJ8CAESIOWPEUBUq4ATLY83P3vLknmWlKYjKVwTgB1z7hYGdyHPIkbbU3ho25Om5AsuLUdsAPiEnyRGbtUUDxrvSoz5T1OVY363dN08cN8diJJro+AE/Zv4QMnq9Vbu8FD237YkLV1bnX/t29ZMMg4I4KvX4vf/////ARDwLg=="  ]}

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1//transform/transformations/tokenization/restore/sample-transform

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

»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

{
  "limit": 3,
  "continuation": "2F1nUpUKMZUBnwQ77qByt1"
}

{  "limit": 3,  "continuation": "2F1nUpUKMZUBnwQ77qByt1"}

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1//transform/transformations/tokenization/export-decoded/sample-transform

$ 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

{
  "data": {
    "continuation": "4hELrrmGAwhHFjmMFny",
    "values": [
      {
        "plaintext": "dmFsdWUtMA==",
        "token": "Q4tYgFXHxUaPhDdV9rx2CduZGPxjYpAp1K523AUsNM5A2Z6DrXj3zz"
      },
      {
        "plaintext": "dmFsdWUtMg==",
        "token": "Q4tYgFXHxUNyMfqRW6fA82DYvMigwdf6JjATauyVzqx2SsmUShMhN5",
        "expiration_time": "2021-03-15T00:31:10Z"
      },
      {
        "plaintext": "dmFsdWUtMQ==",
        "token": "Q4tYgFXHxUNtW27owABRv5GjuxjXTCGebPr7xkqRAY18YVmfZsk2MV"
      }
    ]
  }
}

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

»Parameters

• transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/transform/tokenization/keys/transform_name/rotate

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

»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

[
  {
    "min_decryption_version": 1
  }
]

[  {    "min_decryption_version": 1  }]

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/tokenization/keys/transform_name/config

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

»Sample Request

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

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

»Parameters

• transform_name (string: <required>) – Specifies the transform name to use for this operation. This is specified as part of the URL.

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform/tokenization/keys/:transform_name

$ curl \    --header "X-Vault-Token: ..." \    --request LIST \    --data @payload.json \    http://127.0.0.1:8200/v1/transform/tokenization/keys/:transform_name

»Sample Response

{
  "data": {
    "latest_version": 1,
    "min_available_version": 0,
    "min_decryption_version": 1,
    "name": "transform_name"
  }
}

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

»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

{
  "min_available_version": 1
}

{  "min_available_version": 1}

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/transform//transform/tokenization/keys/:transform_name/trim

$ curl \    --header "X-Vault-Token: ..." \    --request LIST \    --data @payload.json \    http://127.0.0.1:8200/v1/transform//transform/tokenization/keys/:transform_name/trim