Tokenize
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 stringsList of tenant IDs to enforce on the request.
Path parameters
collection
- string required*The name of a collection.
Query parameters
expiration_secs
- stringToken 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
- stringThe transaction ID to attach to the token.
adhoc_reason
- stringAn ad-hoc reason for accessing the Vault data. Required when
reason
is set toOther
.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
- booleanReloads the cache before the action.
Request body
Details of the tokenization request.
- application/json
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 eitherfields
orencrypted
must be supplied.id
- stringThe ID of an object.
fields
- objectA 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
- objectAn encrypted object.
ciphertext
- string required*The encrypted object base64 cipher text.
scope
- stringThe scope used to encrypt the object. By default, it uses the scope of the encrypted object.
request_index
- integerThe index of the object in the request array.
Example{
"fields": {
"first_name": "John",
"email": "patfar@example.com"
}
}props
- array of stringsA list of the properties to tokenize.
Each string:The name of a property.
token_id
- stringUser 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
andpointer
types, it must be unique. Forpci
andpci_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. Fordeterministic
type, it must align exactly with the deterministic ID based on the collection, tokenized object, property values, and scope.scope
- stringA classification for the token. By default for these token types:
deterministic
,pci
andpci_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 withglobal:
.tags
- array of stringsTags to attach to the token. Maximum 10.
Each string:ensure_unique_tenant_tags
- array of stringsTags 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
- booleanWhen
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 stringsProperties used by the format preserving template for the ID generation. The templates require these properties:
- the
primary_account_number
template requires a property of typeCC_NUMBER
. The token ID is generated from this property by retaining the first six and last four digits and randomizing the remaining digits.
- the
fptemplate
- stringThe 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.
[
{
"type": "pointer",
"object": {
"id": "cc9a39c5-4734-4786-b317-e16705d5128f"
},
"props": [
"phone_number"
]
}
]
Possible responses
- 200
- 400
- 401
- 403
- 404
- 405
- 409
- 410
- 500
- 503
The request is successful.
- application/json
token_id
- string required*The ID of the token.
object_id
- stringThe ID of the newly added object, applicable for tokenizing with store_object is true.
[
{
"token_id": "de15a638-354a-11ed-a261-0242ac120002",
"object_id": "cc9a39c5-4734-4786-b317-e16705d5128f"
}
]
The request is invalid.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1001",
"message": "The access reason is missing.",
"context": {
"reason": null
}
}
Authentication credentials are incorrect or missing.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1005",
"message": "The request is unauthorized.",
"context": {}
}
The caller doesn't have the required access rights.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"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
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"objectid": "credit_cadr",
"error_code": "PV3003",
"message": "One or more values are invalid."
}
The operation is not allowed.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1026",
"message": "The operation is not allowed in in-memory mode.",
"context": {}
}
A conflict occurs.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV3218",
"message": "Concurrent conflicting updates to the same object.",
"context": {}
}
Access to a resource that is no longer available occurs.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1033",
"message": "The resource is gone.",
"context": {}
}
An error occurs on the server.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1000",
"message": "Something went wrong",
"context": {}
}
The service is unavailable.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1009",
"message": "The operation timed out on the server.",
"context": {}
}
Path parameters
Query parameters
Headers
Request body
Code examples