Skip to main content

Tokenize

post
/api/pvlt/1.0/data/collections/{collection}/tokens

Creates a token that reference the values of an object's properties. The token ID is partially or wholly randomly-generated and, therefore, is not sensitive. Supports bulk operations.

The returned token IDs are in the same order as the object IDs in the request. No tokens are created if any object IDs are invalid or not found.

If this operation is called for an object ID and properties that have a token:

  • Any token tags are appended to the existing token.
  • If an expiration is specified, then the token expiry is updated. If an expiration is not specified, the token expiry is updated if the default settings result in an expiry date after the token's current expiry date.

The operation can optionally include a transaction ID. This is an arbitrary string included in the request using the transaction_id query parameter. If a transaction ID is included, the token is associated with the transaction ID. The transaction ID can be used to retrieve the token ID by calling the get by transaction ID operation. A transaction ID is unique to the operation and collection. It cannot be used again on future calls to the tokenize operation on the same collection. If multiple tokens are created in the tokenize operation (bulk), all the tokens are associated with the transaction ID.

The role performing this operation must have both of these:

  • The CapTokensWriter capability.
  • At least one allowing policy and no denying policies for the tokenize operation for each of the collection properties specified in the call.

See identity and access management for more information about how capabilities are used to control access to operations and policies are used to control access to data.

Request

Header parameters

  • X-Tenant-Id - array of strings

    List of tenant IDs to enforce on the request.

Path parameters

  • collection - string required*

    The name of a collection.

Query parameters

  • expiration_secs - string

    Token expiration time in seconds. If not set, the default expiration time is used. See the PVAULT_EXPIRATION_TOKENS variable. If set to an empty value, the token will be marked to not expire.

  • transaction_id - string

    The transaction ID to attach to the token.

  • adhoc_reason - string

    An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.

  • reason - string required*

    Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.

  • reload_cache - boolean

    Reloads the cache before the action.

Request body

Details of the tokenization request.

array of objects required*
Each object:
  • type - string required*

    The type of the token:

    • randomized – token that represent the property values as they were when the token was created. For non-format preserving tokens, the token ID is taken from the token_id parameter of the request (if applicable) or randomly assigned a unique ID.
    • pointer – token that represent the property values as they are when the request to detokenize is made. For non-format preserving tokens, the token ID is taken from the token_id parameter of the request (if applicable) or randomly assigned a unique ID.
    • pci – token that represent property values as they were when the token was created. The token ID reuses the ID of an existing token where both tokens are created on the same collection with the same values and scope. Otherwise, the token ID is either randomly assigned, or taken from the token_id parameter of the request (if applicable).
    • pci_oneway – PCI token that cannot be detokenized.
    • deterministic - token that is assigned a deterministic ID based on the collection, tokenized object, property values, and scope.
  • object - object required*

    The input object, defined as one and only one of the following properties.

    • id: the ID of an object.
    • fields: property values of an object.
    • encrypted: an encrypted object.
    • request_index: the index of the object in the request array.

    In stateless mode, id is not supported and either fields or encrypted must be supplied.

    • id - string

      The ID of an object.

    • fields - object

      A list of maps of object properties and their values.

      Example
      {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
      }
    • encrypted - object

      An encrypted object.

      • ciphertext - string required*

        The encrypted object base64 cipher text.

      • scope - string

        The scope used to encrypt the object. By default, it uses the scope of the encrypted object.

    • request_index - integer

      The index of the object in the request array.

    Example
    {
    "fields": {
    "first_name": "John",
    "email": "patfar@example.com"
    }
    }
  • props - array of strings

    A list of the properties to tokenize.

    Each string:

    The name of a property.

  • token_id - string

    User provided token ID, up to 128 chars, using letters (a-z, A-Z), numbers (0-9), hyphens (-), and underscores (_). The user provided ID can not be used with 'fptemplate' and 'fpprops' parameters. For randomized and pointer types, it must be unique. For pci and pci_oneway types, it must reuse the ID of any existing token which was created on the same collection with the same values and scope. Otherwise, it should be unique. For deterministic type, it must align exactly with the deterministic ID based on the collection, tokenized object, property values, and scope.

  • scope - string

    A classification for the token. By default for these token types: deterministic, pci and pci_oneway, the scope is bound per collection. This implies that two identical tokens with the same scope on different collection will result with different token_ids. You can force the scope to apply globally by setting the suffix of the scope value to start with global:.

  • tags - array of strings

    Tags to attach to the token. Maximum 10.

    Each string:
  • ensure_unique_tenant_tags - array of strings

    Tags to validate as unique in tenant scope. Must be subset of 'tags'. Note: this operation has a performance impact to be able to ensure the uniqueness of the tags prior to the insertion operation.

    Each string:
  • store_object - boolean

    When fields is included in the request body, whether to store the property values as an object in the collection. The token is owned by the new object. Default is false.

  • fpprops - array of strings

    Properties used by the format preserving template for the ID generation. The templates require these properties:

    • the primary_account_number template requires a property of type CC_NUMBER. The token ID is generated from this property by retaining the first six and last four digits and randomizing the remaining digits.
    Each string:
  • fptemplate - string

    The template used to format the generated ID. Supports:

    • primary_account_number that generates an ID that is a valid 16-digit PAN (credit card number). If empty, the format of the ID is a UUID.
Example
[
{
"type": "pointer",
"object": {
"id": "cc9a39c5-4734-4786-b317-e16705d5128f"
},
"props": [
"phone_number"
]
}
]

Possible responses

The request is successful.

array of objects required*
Each object:
  • token_id - string required*

    The ID of the token.

  • object_id - string

    The ID of the newly added object, applicable for tokenizing with store_object is true.

Example
[
{
"token_id": "de15a638-354a-11ed-a261-0242ac120002",
"object_id": "cc9a39c5-4734-4786-b317-e16705d5128f"
}
]

Try the API

Authorization

Path parameters

Query parameters

Headers

Request body

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example