Skip to main content

Tokenization

The Vault tokenization engine enables you to create a non-sensitive token that references sensitive data. You can think of a token as a "handle" to the data. Only authorized clients can then detokenize to obtain the referenced data value. As a token doesn't include the original data, it can travel, without risk of exposure, through non-secure systems. This also has the advantage of keeping those other systems out of compliance scope.

Tokens can weakly preserve some properties of the data, such as format and order. For example, a token could maintain the format of an email address such as 7d6496e3-8b9b-44d9@gmail.com. This feature helps minimize changes in client applications where they expect or validate the format for items such as credit card and email.

Vault supports five types of tokens:

  • deterministic - tokens that are assigned a deterministic ID based on the collection, tokenized object, property values, and scope.
  • pci – tokens 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 tokens that cannot be detokenized.
  • pointer – tokens that represent the property values as they are when the request to detokenize is made.
  • randomized – tokens 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.

See the tokenization guides for more information.

Example​

Assume Vault contains an employees collection with these people:

+--------------------------------------+----------------+
|                  id                  |      email     |
+--------------------------------------+----------------+
| 7d6496e3-8b9b-44d9-b924-b733f82e3fe4 | john@gmail.com |
| b91d6440-1e42-4703-bc7d-8fb026898dbb | mary@gmail.com |
| f9e17299-bc8b-4626-89c9-53760878e419 | eric@gmail.com |
+--------------------------------------+----------------+

Mary's email address can be tokenized using the Tokenize REST API operation, or, as shown here, the Tokenize CLI command.

pvault token create \
  --collection employees \
  --object-id b91d6440-1e42-4703-bc7d-8fb026898dbb \
  --props email \
  --type pci
+--------------------------------------+
|                token                 |
+--------------------------------------+
| 6cbdc2c9-3d81-41bc-920b-47b8a07bd127 |
+--------------------------------------+

Then detokenized:

pvault token detokenize \
  --collection employees \
  --token-id 6cbdc2c9-3d81-41bc-920b-47b8a07bd127
+-------+----------------+
| NAME  |     VALUE      |
+-------+----------------+
| email | mary@gmail.com |
+----–--+----------------+

The token can be deleted like this:

pvault token delete \
  --collection employees \
  --token-id 6cbdc2c9-3d81-41bc-920b-47b8a07bd127

Now, any attempt to detokenize the token results in an error:

pvault token detokenize \
  --collection employees \
  --token-id 6cbdc2c9-3d81-41bc-920b-47b8a07bd127 
2022/04/12 09:35:00 Error code: PV3009, Status code: 404, Message: The token is not found., Context: map[]

On this page