Search tokens

post

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

Lists tokens with their metadata.

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 CapTokensReader capability.
• At least one allowing policy and no denying policies for the read operation for the tokens resource of the specified collection.

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

• options - array of strings

  Options for the operation. Options include:

  • archived – whether to search only archived tokens. If not specified, search only active tokens.
  • 'include_aggregated_data' - whether to include aggregated data in the response. If not specified, aggregated data is not included.

  Each string:

  Allowed values: archived, 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.

Request body

The token query.

application/json

object required*

Additional properties: falseProperties:

• object_ids - array of strings

  Comma-separated list of object IDs.

  Each string:

  Format: uuidExample: "463a83d0-a816-4902-abba-2486e0c0a0bb"
• token_ids - array of strings

  Comma-separated list of token IDs.

  Each string:

  Example: "49303e72-35e3-11ed-a261-0242ac120002"
• tags - array of strings

  Comma-separated list of tags.

  Each string:

  Max length: 256Example: "credit_cards"

Example

{
  "object_ids": [
    "463a83d0-a816-4902-abba-2486e0c0a0bb"
  ],
  "token_ids": [
    "49303e72-35e3-11ed-a261-0242ac120002"
  ],
  "tags": [
    "credit_cards"
  ]
}

Possible responses

200

The request is successful.

application/json

array of objects required*

Each 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

[
  {
    "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

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