Skip to main content

Retrieve a token

Learn how to retrieve token data​

After tokenizing data, you may want to get the data from the token. This process is called "detokenization." You can detokenize pci, pointer, deterministic and randomized tokens types. In addition to detokenizing tokens, you may want to retrieve token metadata such as the expiration date, token type, tags, etc. You can obtain metadata for all token types.

You select the tokens to return from the detokenize and search tokens (to retrieve metadata) operations using at least one of the following parameters:

  1. token_ids - A list of token IDs evaluated separately. Only existing and active IDs are returned.
  2. object_ids - A list of object IDs evaluated separately. If not empty, all the IDs must exist.
  3. tags - A list of tags that will be searched on the tokens.

This results in the following selection options:

  • Using only token_ids: returns all tokens that match any of the token IDs.
  • Using only object_ids: returns all tokens created for any of the object IDs.
  • Using only tags: returns all tokens that have at least all the tags.
  • Using both token_ids and object_ids: returns all tokens that match any of the token IDs where those tokens were created for one of the object IDs.
  • Using token_ids and tags: returns all tokens that match any of the token IDs and also have at least all of the tags.
  • Using object_ids and tags: returns all tokens created for any of the object IDs and also have at least all of the tags.
  • Using token_ids, object_ids, and tags: returns all tokens that:
    1. Match any of the token IDs for tokens that were created for one of the object IDs
    2. Have at least all of the tags.
tip

You can only return active (unarchived) tokens. To return an archived token, first, make it active by updating its expiration time using Update tokens.

While archived (expired) tokens aren't returned to the caller, request or search for archived (expired) tokens will not result in an error. When your request is processed, the archived tokens are first removed. Your request may still return a 200 status code.

A request for a single archived token, returns an empty array of results. A request for multiple objects, some of which are archived returns only the active items. The reason for this behavior is that token operations are treated as batch operations.

Detokenize using token ID​

Overview​

To obtain the underlying values of tokens using token IDs:

  1. Determine the IDs of the tokens.
  2. Use the CLI detokenize command or REST API detokenize operation, passing the token IDs.

Step-by-step​

Say you want to get the value of a token on the paymentinfo collection with the ID d27923c6-5d16-41e3-89ee-118b05a25372.

You retrieve the value using the CLI like this:

pvault token detokenize \
  -t d27923c6-5d16-41e3-89ee-118b05a25372 \
  --collection paymentinfo

You get a response similar to this:

+--------------------------------------+--------------------------+
|               token_id               |        cc_number         |
+--------------------------------------+--------------------------+
| d27923c6-5d16-41e3-89ee-118b05a25372 |     4012888888881881     |
+--------------------------------------+--------------------------+

Or using the REST API like this:

curl -s -X GET \
  --url 'http://localhost:8123/api/pvlt/1.0/data/collections/paymentinfo/tokens?token_ids=d27923c6-5d16-41e3-89ee-118b05a25372&reason=AppFunctionality' \
  -H 'Authorization: Bearer pvaultauth' \
  -H 'Content-Type: application/json'

You get a response similar to this:

[
  {
    "fields": {
      "cc_number": "4012888888881881"
    },
    "token_id": "d27923c6-5d16-41e3-89ee-118b05a25372"
  }
]

Search token by token ID​

Overview​

To obtain the metadata of tokens using token IDs:

  1. Determine the IDs of the tokens.
  2. Use the CLI search tokens command or [REST API search tokens metadata operation, passing the token IDs.

Step-by-step​

Say you want to get the metadata for a token on the paymentinfo collection with the ID d27923c6-5d16-41e3-89ee-118b05a25372.

You retrieve the value using the CLI like this:

pvault token info \
  --t d27923c6-5d16-41e3-89ee-118b05a25372 \
  --collection paymentinfo

You get a response similar to this:

+-------------------------------+--------------------------------------+------+---------+-------------------------------+-----------------+---------------------------+---------------------+--------------------------------------+------+
| max_effective_expiration_time |               token_id               | type |  scope  |         creation_time         | expiration_time | effective_expiration_time | effective_tenant_id |             object_id                | tags |
+-------------------------------+--------------------------------------+------+---------+-------------------------------+-----------------+---------------------------+---------------------+--------------------------------------+------+
|                               | d27923c6-5d16-41e3-89ee-118b05a25372 | pci  | default | Sat, 16 Jul 2022 16:28:36 UTC |                 |                           |                     | b3436a70-5f2d-48f6-b887-6a87087f8b03 | []   |
+-------------------------------+--------------------------------------+------+---------+-------------------------------+-----------------+---------------------------+---------------------+--------------------------------------+------+

Or using the REST API like this:

curl -s -X POST \
  --url 'http://localhost:8123/api/pvlt/1.0/data/collections/paymentinfo/query/tokens?reason=AppFunctionality' \
  -H 'Authorization: Bearer pvaultauth' \
  -H 'Content-Type: application/json' \
  -d '{ "token_ids": ["d27923c6-5d16-41e3-89ee-118b05a25372"] }'

You get a response similar to this:

[
  {
    "token_id": "d27923c6-5d16-41e3-89ee-118b05a25372",
    "type": "pci",
    "scope": "default",
    "tokens": [
      {
        "creation_time": "2022-07-16T16:28:37.182702796Z",
        "expiration_time": null,
        "effective_expiration_time": null,
        "object_id": "d27923c6-5d16-41e3-89ee-118b05a25372",
        "tags": []
      }
    ]
  }
]

Search tokens for an object​

Overview​

You may want to know what tokens an object or objects have. To get a list of the objects’ token IDs and token metadata:

  1. Determine the IDs of the objects.
  2. Use the CLI search tokens command or [REST API search tokens metadata operation, passing the object IDs.

Step-by-step​

Say you want to get the metadata for an object on the paymentinfo collection with the ID 3afa094a-6443-4e6f-926c-2526151f892d where the collection contains these tokens:

+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
|               token_id               |    type    |  scope  |      max_expiration_time      | tags |         creation_time         |        expiration_time        |              object_id               |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
| 32077c80-3792-4a45-a957-e365bb1c9533 |    pci     | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 6b0323e6-b587-4f1b-8cfc-712fc4a4781f |
| 32077c80-3792-4a45-a957-e365bb1c9533 |  pointer   | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
| d27923c6-5d16-41e3-89ee-118b05a25372 | randomized | default | Thu, 21 Jul 2022 00:19:47 UTC | [b]  | Wed, 20 Jul 2022 00:19:47 UTC | Thu, 21 Jul 2022 00:19:47 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+

You retrieve the object’s tokens and their metadata using the CLI like this:

pvault token info \
  --object-id "3afa094a-6443-4e6f-926c-2526151f892d" \
  --collection paymentinfo

You get a response similar to this:

+--------------------------------------+------------+------------+-----------------------------------------+------+------------------------------------+-------------------------------+-------------------------------------------+--------------------------------------+
|               token_id               |    type    |   scope    |      max_effective_expiration_time      | tags |         creation_time              |   expiration_time             |         effective_expiration_time         |              object_id               |
+--------------------------------------+------------+------------+-----------------------------------------+------+------------------------------------+-------------------------------+-------------------------------------------+--------------------------------------+
| 32077c80-3792-4a45-a957-e365bb1c9533 |   pointer  |   default  |                                         | [a]  |   Sat, 16 Jul 2022 16:28:36 UTC    |                               |                                           | 3afa094a-6443-4e6f-926c-2526151f892d |
| d27923c6-5d16-41e3-89ee-118b05a25372 | randomized |   default  |                                         | [b]  |   Sat, 16 Jul 2022 16:28:36 UTC    |                               |                                           | 3afa094a-6443-4e6f-926c-2526151f892d |
+--------------------------------------+------------+------------+-----------------------------------------+------+------------------------------------+-------------------------------+-------------------------------------------+--------------------------------------+

Or using the REST API like this:

curl -s -X POST \
  --url 'http://localhost:8123/api/pvlt/1.0/data/collections/paymentinfo/query/tokens?reason=AppFunctionality' \
  -H 'Authorization: Bearer pvaultauth' \
  -H 'Content-Type: application/json' \
  -d '{ "object_ids": ["3afa094a-6443-4e6f-926c-2526151f892d"] }'

You get a response similar to this:

[{"token_id":"d27923c6-5d16-41e3-89ee-118b05a25372","type":"pointer","scope":"default","tokens":[{"tags":["a"],"creation_time":"2022-07-16T16:28:37.182702796Z","expiration_time":null,"effective_expiration_time":null,"object_id":"3afa094a-6443-4e6f-926c-2526151f892d"}],"agg":{"max_effective_expiration_time":null}},{"token_id":"32077c80-3792-4a45-a957-e365bb1c9533","type":"randomized","scope":"default","tokens":[{"tags":["b"],"creation_time":"2022-07-16T16:28:37.182702796Z","expiration_time":null,"effective_expiration_time":null,"object_id":"3afa094a-6443-4e6f-926c-2526151f892d"}],"agg":{"max_effective_expiration_time":null}}]

Search tokens by tag​

Overview​

You may want to know what tokens exist for a tag or tags. To get a list of the objects’ token IDs and token metadata:

  1. Determine the tags.
  2. Use the CLI search tokens command or [REST API search tokens metadata operation, passing the tags.

Step-by-step​

Say you want to get the metadata for tokens on the paymentinfo collection with the a tag, where the collection contains these tokens:

+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
|               token_id               |    type    |  scope  |      max_expiration_time      | tags |         creation_time         |        expiration_time        |              object_id               |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
| 32077c80-3792-4a45-a957-e365bb1c9533 |    pci     | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 6b0323e6-b587-4f1b-8cfc-712fc4a4781f |
| 32077c80-3792-4a45-a957-e365bb1c9533 |  pointer   | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
| d27923c6-5d16-41e3-89ee-118b05a25372 | randomized | default | Thu, 21 Jul 2022 00:19:47 UTC | [b]  | Wed, 20 Jul 2022 00:19:47 UTC | Thu, 21 Jul 2022 00:19:47 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+

You retrieve the tagged objects’ tokens and their metadata using the CLI like this:

pvault token info --tag=a --collection paymentinfo

You should get a response similar to this:

+--------------------------------------+-------------+------------+-----------------------------------------+------+-----------------------------------+-------------------------------+-----------------------------------------+--------------------------------------+
|               token_id               |    type     |   scope    |      max_effective_expiration_time      | tags |          creation_time            |        expiration_time        |        effective_expiration_time        |              object_id               |
+--------------------------------------+-------------+------------+-----------------------------------------+------+-----------------------------------+-------------------------------+-----------------------------------------+--------------------------------------+
| 32077c80-3792-4a45-a957-e365bb1c9533 |   pointer   |   default  |                                         | [a]  |   Sat, 16 Jul 2022 16:28:36 UTC   |                               |                                         | 32077c80-3792-4a45-a957-e365bb1c9533 |
| 32077c80-3792-4a45-a957-e365bb1c9533 |   pci       |   default  |                                         | [a]  |   Sat, 16 Jul 2022 16:28:36 UTC   |                               |                                         | 6b0323e6-b587-4f1b-8cfc-712fc4a4781f |
+--------------------------------------+-------------+------------+-----------------------------------------+------+-----------------------------------+-------------------------------+-----------------------------------------+--------------------------------------+

Or using the REST API like this:

curl -s -X POST \
    --url 'http://localhost:8123/api/pvlt/1.0/data/collections/paymentinfo/query/tokens?reason=AppFunctionality' \
    -H 'Authorization: Bearer pvaultauth' \
    -H 'Content-Type: application/json' \
    -d '{ "tags": ["a"] }'

You get a response similar to this:

[{"token_id":"32077c80-3792-4a45-a957-e365bb1c9533","type":"pointer","scope":"default","tokens":[{"tags":["a"],"creation_time":"2022-07-16T16:28:37.182702796Z","expiration_time":null,"effective_expiration_time":null,"object_id":"32077c80-3792-4a45-a957-e365bb1c9533"}],"agg":{"max_effective_expiration_time":null}},{"token_id":"32077c80-3792-4a45-a957-e365bb1c9533","type":"pci","scope":"default","tokens":[{"tags":["a"],"creation_time":"2022-07-16T16:28:37.182702796Z","expiration_time":null,"effective_expiration_time":null,"object_id":"6b0323e6-b587-4f1b-8cfc-712fc4a4781f"}],"agg":{"max_effective_expiration_time":null}}]

Search tokens using multiple parameters​

You may want to know what tokens exist for a combination of object IDs, token IDs, or tags. To get a list of the objects’ token IDs and token metadata:

  1. Determine the object IDs, token IDs, or tags.
  2. Use the CLI search tokens command or [REST API search tokens metadata operation, passing the object IDs, token IDs, or tags.

Step-by-step​

Say you want to get the metadata for all tokens for the object with the ID 32077c80-3792-4a45-a957-e365bb1c9533 and token ID d27923c6-5d16-41e3-89ee-118b05a25372 from the paymentinfo collection, where the collection contains these tokens:

+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
|               token_id               |    type    |  scope  |      max_expiration_time      | tags |         creation_time         |        expiration_time        |              object_id               |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+
| 32077c80-3792-4a45-a957-e365bb1c9533 |    pci     | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 6b0323e6-b587-4f1b-8cfc-712fc4a4781f |
| 32077c80-3792-4a45-a957-e365bb1c9533 |  pointer   | default | Thu, 21 Jul 2022 00:19:28 UTC | [a]  | Wed, 20 Jul 2022 00:19:28 UTC | Thu, 21 Jul 2022 00:19:28 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
| d27923c6-5d16-41e3-89ee-118b05a25372 | randomized | default | Thu, 21 Jul 2022 00:19:47 UTC | [b]  | Wed, 20 Jul 2022 00:19:47 UTC | Thu, 21 Jul 2022 00:19:47 UTC | 3afa094a-6443-4e6f-926c-2526151f892d |
+--------------------------------------+------------+---------+-------------------------------+------+-------------------------------+-------------------------------+--------------------------------------+

You retrieve the tokens and their metadata using the CLI like this:

pvault token info \
  --collection paymentinfo \
  --object-id 32077c80-3792-4a45-a957-e365bb1c9533 \
  --token-id d27923c6-5d16-41e3-89ee-118b05a25372

You get a response similar to this:

+-----------------------------------------+--------------------------------------+----------------+------------+------------------------------------+-------------------------------+-----------------------------------------+---------------------+--------------------------------------+------+
|      max_effective_expiration_time      |               token_id               |  type          |   scope    |            creation_time           |        expiration_time        |        effective_expiration_time        | effective_tenant_id |           object_id                  | tags |
+-----------------------------------------+--------------------------------------+----------------+------------+------------------------------------+-------------------------------+-----------------------------------------+---------------------+--------------------------------------+------+
|                                         | d27923c6-5d16-41e3-89ee-118b05a25372 |   randomized   |  default   |   Sat, 16 Jul 2022 16:28:36 UTC    |                               |                                         |                     | 32077c80-3792-4a45-a957-e365bb1c9533 | [b]  |
+-----------------------------------------+--------------------------------------+----------------+------------+------------------------------------+-------------------------------+-----------------------------------------+---------------------+--------------------------------------+------+

On this page