Detokenize tokens

get

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

Returns the object property values for tokens.

The tokens returned by this operation are defined using three query parameters: token_ids, object_ids, and tags. The operation returns an empty response if it finds no matches. See the Retrieve a token guide for more information about how to match tokens for this operation.

The role performing this operation must have all of these:

• The CapTokensDetokenizer capability.
• Policies:
  • At least one allowing policy and no denying policies for the detokenize operation for each of the collection properties that are tokenized by tokens specified in the query.
  • At least one allowing policy and no denying policies for the read operation for each of the collection properties that are tokenized by tokens specified in the query.

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

• object_ids - array of strings

  Comma-separated list of object IDs.

  Each string:

  Format: uuid
• tags - array of strings

  Comma-separated list of tags.

  Each string:

  Max length: 256Example: "credit_cards"
• token_ids - array of strings

  Comma-separated list of token IDs.

• props - array of strings

  The list of property names and transformations. To include multiple names and transformations, provide a comma-separated list. For example, props=first_name,last_name,email.mask.

  Each string:

  The name of a property or a transformation in the format <property-name>.<transformer-name>.

  Example: "ssn.mask"
• options - array of strings

  Options for the operation. Options include:

  • include_metadata - show token metadata in the response.
  • 'include_aggregated_data' - whether to include aggregated data in the response. If not specified, aggregated data is not included. Only applicable if include_metadata is set.

  Each string:

  Allowed values: include_metadata, include_aggregated_data
• 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.

Possible responses

200

The request is successful.

application/json

array of objects required*

Each object:

Additional properties: falseProperties:

• fields - object required*

  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"
  }
• token_id - string required*

  The token ID.

  Example: "49303e72-35e3-11ed-a261-0242ac120002"
• metadata - object

  Additional properties: falseProperties:

  • agg - object

    Additional properties: falseProperties:

    • max_effective_expiration_time - string

      Latest expiry of all tokens with the token ID (UTC).

      Format: date-timeNullable: true
  • 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
  • scope - string required*

    The scope of the tokens.

    Example: "default"
  • token_id - string required*

    The shared ID of the tokens.

    Example: "49303e72-35e3-11ed-a261-0242ac120002"
  • tokens - array of objects required*

    The metadata for each token.

    Each object:

    Additional properties: falseProperties:

    • creation_time - string required*

      Creation time of the token (UTC).

      Format: date-time
    • effective_expiration_time - string required*

      Effective expiry time of the token (UTC), being the earliest of the expiry time of the token or the object owning the token, if any.

      Format: date-timeNullable: true
    • expiration_time - string required*

      Expiry time of the token (UTC).

      Format: date-timeNullable: true
    • object_id - string

      The object this token is for.

      Format: uuid
    • effective_tenant_id - string

      The tenant ID of the tokens.

    • tags - array of strings required*

      Tags associated with the token. When token ID is reused, this is all the tags from the tokens that share the ID.

      Each string:

      Max length: 256Example: "credit_cards"

Example

[
  {
    "fields": {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
    },
    "token_id": "49303e72-35e3-11ed-a261-0242ac120002",
    "metadata": {
      "agg": {
        "max_effective_expiration_time": "2019-08-24T14:15:22Z"
      },
      "type": "pci",
      "scope": "default",
      "token_id": "49303e72-35e3-11ed-a261-0242ac120002",
      "tokens": [
        {
          "creation_time": "2019-08-24T14:15:22Z",
          "effective_expiration_time": "2019-08-24T14:15:22Z",
          "expiration_time": "2019-08-24T14:15:22Z",
          "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
          "effective_tenant_id": "string",
          "tags": [
            "credit_cards"
          ]
        }
      ]
    }
  }
]

400

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
  }
}

401

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": {}
}

403

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"
  }
}

404

The requested resource is not found.

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": "PV1004",
  "message": "The collection is not found.",
  "context": {}
}

405

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": {}
}

409

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": {}
}

410

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": {}
}

500

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": {}
}

503

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

Object_ids:

Tags:

Token_ids:

Props:

Options:

Adhoc_reason:

Reason*:

Custom_audit:

Reload_cache:

Headers

X-Tenant-Id:

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

Code examples

Example