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.
Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 40Example: "customers"

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.
Match pattern: ^[0-9]*$
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.
Allowed values: AppFunctionality, Analytics, Notifications, Marketing, ThirdPartyMarketing, FraudPreventionSecurityAndCompliance, AccountManagement, Maintenance, DataSubjectRequest, Other
custom_audit - string
Custom audit information to be included in the audit log.
reload_cache - boolean
Reloads the cache before the action.

Request body

Details of the tokenization request.

application/json

array of objects required*

Min items: 1Each object:

Additional properties: falseProperties:

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.
Allowed values: pci, pci_oneway, pointer, randomized, deterministic
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.
Min properties: 1Max properties: 1Additional properties: falseProperties:
- id - string
  The ID of an object.
  Format: uuid
- fields - object
  A list of maps of object properties and their values.
  Additional properties: true
  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.
  Additional properties: falseProperties:
  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.
  Greater than or equal to: 0
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.
Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
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:.
Default: default
tags - array of strings
Tags to attach to the token. Maximum 10.
Less than or equal to: 10Each string:
Max length: 256Example: "credit_cards"
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.
Less than or equal to: 10Each string:
Max length: 256Example: "credit_cards"
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:
Example: "credit_card_no"
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.
Allowed values: primary_account_number

Example
[
  {
    "type": "pointer",
    "object": {
      "id": "cc9a39c5-4734-4786-b317-e16705d5128f"
    },
    "props": [
      "phone_number"
    ]
  }
]

Possible responses

The request is successful.

application/json

array of objects required*

Each object:

Additional properties: falseProperties:

token_id - string required*
The ID of the token.
Example: "de15a638-354a-11ed-a261-0242ac120002"
object_id - string
The ID of the newly added object, applicable for tokenizing with store_object is true.
Format: uuidExample: "cc9a39c5-4734-4786-b317-e16705d5128f"

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

The request is invalid.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1001",
  "message": "The access reason is missing.",
  "context": {
    "reason": null
  }
}

Authentication credentials are incorrect or missing.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1005",
  "message": "The request is unauthorized.",
  "context": {}
}

The caller doesn't have the required access rights.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1007",
  "message": "The operation is forbidden due to missing capabilities.",
  "context": {
    "username": "WebServer"
  }
}

The collection, objects, or properties aren't found or are missing.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "objectid": "credit_cadr",
  "error_code": "PV3003",
  "message": "One or more values are invalid."
}

The operation is not allowed.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1026",
  "message": "The operation is not allowed in in-memory mode.",
  "context": {}
}

A conflict occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV3218",
  "message": "Concurrent conflicting updates to the same object.",
  "context": {}
}

Access to a resource that is no longer available occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1033",
  "message": "The resource is gone.",
  "context": {}
}

An error occurs on the server.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1000",
  "message": "Something went wrong",
  "context": {}
}

The service is unavailable.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1009",
  "message": "The operation timed out on the server.",
  "context": {}
}

Try the API

Authorization

API key:

Path parameters

Collection*:

Query parameters

Expiration_secs:

Transaction_id:

Adhoc_reason:

Reason*:

Custom_audit:

Reload_cache:

Headers

X-Tenant-Id:

Request body

Content-Type:

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

Code examples

Example

Request​

Header parameters​

Path parameters​

Query parameters​

Request body​

Possible responses​

Try the API

Authorization

Path parameters

Query parameters

Headers

Request body

Code examples

Request

Header parameters

Path parameters

Query parameters

Request body

Possible responses