Skip to main content

Search 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.


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.

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.
    Each string:
  • 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.

  • reload_cache - boolean

    Reloads the cache before the action.

Request body

The token query.

object required*
  • object_ids - array of strings

    Comma-separated list of object IDs.

    Each string:
  • token_ids - array of strings

    Comma-separated list of token IDs.

    Each string:
  • tags - array of strings

    Comma-separated list of tags.

    Each string:
"object_ids": [
"token_ids": [
"tags": [

Possible responses

The request is successful.

array of objects required*
Each object:
  • agg - object required*
    • max_effective_expiration_time - string

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

  • type - string required*

    The type of the token:

    • deterministic - token that is assigned a deterministic ID based on the collection, tokenized object, property values, and scope.
    • 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 randomly assigned.
    • pci_oneway – PCI token that cannot be detokenized.
    • pointer – token that represent the property values as they are when the request to detokenize is made.
    • randomized – token that represent the property values as they were when the token was created. Unlike PCI tokens, for non-format preserving tokens, these tokens are always assigned a unique ID.
  • scope - string required*

    The scope of the tokens.

  • token_id - string required*

    The shared ID of the tokens.

  • tokens - array of objects required*

    The metadata for each token.

    Each object:
    • creation_time - string required*

      Creation time of the token (UTC).

    • 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.

    • expiration_time - string required*

      Expiry time of the token (UTC).

    • object_id - string

      The object this token is for.

    • 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:
"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": [

Try the API


Path parameters

Query parameters


Request body

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

Code examples