Update tokens

patch

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

Updates token data or token metadata tags and expiration properties.

Update token metadata

See the Update a token guide for more information about updating a token's metadata.

Update token data

To update token data, all the tokens must:

have the same token ID.
be token types pci, pci_oneway, or randomized (metadata can be updated in all token types).

To update a token's data, set the object parameter to contain one of these:

Objects stored in Vault by providing their ID.
Fields not stored in Vault by providing a map of their properties and property values. These fields must conform to the schema of the collection specified in the request.
Ciphertext. This enables you to update a token's data with a subset of another ciphertext's properties or with a different encryption type or scope.

Updates to the token's data do not change the token's metadata, token ID, ownership, or lifecycle of the token . However, the data update may affect subsequent tokenizations. For example, if a token of type pci with ID "X" is updated, subsequent tokenizations of the new data have the same token ID "X," while tokenizations of the previous data results in a new token ID. See Tokenization for more information on token types.

note

Update to the token's data overrides the entire existing data.

Permissions

The role performing this operation must have both of these:

The CapTokensWriter capability.
At least one allowing policy and no denying policies for the write operation for the tokens resource of the collection specified in the call.
- Updating a token's metadata requires the write operation for the tokens resource of the collection specified in the call.
- Updating a token's data requires the tokenize operation for each of the collection properties specified in the call.
- For updating both the metadata and the data of a token, only the tokenize operation permission is required.

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.

Query

The tokens returned by this operation are defined using three query parameters: token_ids, object_ids, and tags. If no tokens are matched, status code 404 is returned. See the Retrieve a token guide for more information about how to match tokens for this operation.

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
Expiration time in seconds for the tokens. If not set, the expiry dates of the tokens are not changed. If set to an empty value, the token will be marked to not expire.'
Match pattern: ^[0-9]*$
object_ids - array of strings
Comma-separated list of object IDs.
Each string:
Format: uuid
tags - array of strings
Comma-separated list of tags.
token_ids - array of strings
Comma-separated list of token IDs.
options - array of strings
Options for the operation. Options include:
- archived – whether to update only archived tokens. If not specified, update only active tokens.
Each string:
Allowed values: archived
adhoc_reason - string
An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.
reason - string
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

Update token request details.

application/json

object required*

Additional properties: falseProperties:

tags - array of strings
Replacement tags for the tokens.
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 a subset of 'tags'. Note: The need to ensure the uniqueness of the tags prior to insertion means this feature impacts the operation's performance.
Less than or equal to: 10Each string:
Max length: 256Example: "credit_cards"
object - object
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 update.
Each string:
The name of a property.
Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"

Example
{
  "tags": [
    "credit_cards"
  ],
  "ensure_unique_tenant_tags": [
    "credit_cards"
  ],
  "object": {
    "fields": {
      "first_name": "John",
      "email": "patfar@example.com"
    }
  },
  "props": [
    "first_name"
  ]
}

Possible responses

The request is successful.

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 or reason aren't found or are missing, the reason is set to other but no adhoc_reason is provided, no token query parameters are provided, or the query finds no matching tokens.

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": "PV3009",
  "message": "The token is not found."
}

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:

Object_ids:

Tags:

Token_ids:

Options:

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

Update token metadata​

Update token data​

Permissions​

Query​

Request​

Header parameters​

Path parameters​

Query parameters​

Request body​

Possible responses​

Try the API

Authorization

Path parameters

Query parameters

Headers

Request body

Code examples

Update token metadata

Update token data

Permissions

Query

Request

Header parameters

Path parameters

Query parameters

Request body

Possible responses