Skip to main content

Tokenize

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

Creates tokens that reference the values of objects' properties. The token ID is partially or wholly randomly-generated and, therefore, is not sensitive.

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 time to live (TTL) is specified, then the token expiry is updated. If TTL 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 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.

Piiano Vault REST API

Overview
Endpoints
Collections
Collection properties
Data types and transformations
Objects
Tokens
Tokenize
post
Detokenize tokens
get
Delete tokens
delete
Update tokens
patch
Rotate tokens
post
Search tokens
post
IAM
Config Vars
System
powered by Stoplight

Tokenize

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

Creates tokens that reference the values of objects' properties. The token ID is partially or wholly randomly-generated and, therefore, is not sensitive.

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 time to live (TTL) is specified, then the token expiry is updated. If TTL 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 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.

collection
string
required

The name of the collection containing the objects.

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:
AppFunctionalityAnalyticsNotificationsMarketingThirdPartyMarketingFraudPreventionSecurityAndComplianceAccountManagementMaintenanceDataSubjectRequestOther
adhoc_reason
string

An ad-hoc reason for accessing the Vault data.

reload_cache
boolean

Reloads the cache before the action.

ttl
string

Token time to live (TTL) in seconds. If not set, the default TTL is used. See the PVAULT_TTL_TOKENS time to live environment variable.

Match pattern:
^[0-9]*$

Details of the tokenization request.

fpprops
array[string]

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.
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 value:
primary_account_number
object_ids
array[string]<uuid>
required

A list of object IDs to create tokens for.

props
array[string]
required

A list of the properties to tokenize.

reuse_token_id
boolean

Whether to reuse token IDs.

  • If the combination of object ID, property values, and scope are not represented in a token whose ID can be reused, creates a new token and indicates that its ID can be reused.
  • If the combination of object ID, property values, and scope are represented in a token whose ID can be reused, returns the reusable token's ID.

Applies only to VALUE tokens.

Default:
false
reversible
boolean

Whether the tokens can be detokenized.

Default:
true
scope
string

A classification for the tokens.

Default:
default
tags
array[string]

Tags to attach to the tokens. Maximum 10.

type
string
required

The type of tokens to create:

  • VALUE for tokens that represent the property values as they were when the token was created.
  • POINTER for tokens that represent the property values as they are when the request to detokenize is made.
Allowed values:
POINTERVALUE
Auth
:
Parameters
:
:
:
:
:
Body
preparing...