Create a token

Learn how to create tokens in Piiano Vault

Where you want people to access your data from third-party systems, pass data through insecure channels, or work with data without revealing the underlying value, you create tokens to conceal a value behind a non-sensitive ID.

Vault supports five token types:

• deterministic - tokens assigned an ID determined from the combination of 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 you cannot detokenize.
• pointer – tokens that represent the property values as they are when you make a request to detokenize.
• 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.

In addition, tokens can use either UUIDs for their IDs or an ID that preserves the format.

Choose your token type

Determine the most appropriate token type for your use case like this:

• do you want the value represented by the token to be accessible, that is, do you want a token that can be detokenized?
  • for a token that can be detokenized:
    • what value do you want to return when detokenizing?
      • the value at the time the token was created:
        • how do you want the token ID created?
          • tokens get a unique ID: use a randomized token.
          • tokens get the same ID if a token for the same collection, object, values, and scopes and parameters is in the system (otherwise the ID is random): use a pci token.
          • tokens always get the same ID if tokenizing the same collection, object, values, and scopes: use a deterministic token^*.
      • the value at the time the token is detokenized:
        • use a pointer token.
  • for a token that cannot be detokenized:
    • use a pci_oneway token.

* In some cases, you may only need the ID and don't need to store a token. To do this, use the hash tokens CLI command or REST API operation.

Token type by use case

Here are some typical use cases and the token types you might use to address them:

• Let someone obtain a person's current email: use a pointer token.
• Log transactions made by buyers that include the buyers’ credit card details. You want to keep the credit card details secure but be able to access the credit card number if needed: use a randomized token.
• Log transactions made by buyers and want to store the buyers’ credit card details. Do you want to be able to identify all transactions made with the same credit card but don't want users to be able to access the credit card number: use a pci-oneway token.
• Enable support center users to validate a customer's secret phrase without giving users the ability to see customers' secret phrases: use a deterministic token. Then, when the customer provides their secret phrase, generate a new deterministic token and confirm it has the same value as the token used to represent the customer secret phrase.
• Pass tokenized data through a system that validates the format of the data: use an appropriate token type with a format-preserving ID.

Token expiration

When you create a token, it's given an expiration period. If you don't explicitly set the expiration period, it is set to the value of the PVAULT_EXPIRATION_TOKENS environment variable. The default value of PVAULT_EXPIRATION_TOKENS in the standard Vault implementation is null, meaning that tokens never expire. See Object life cycle for more information on token expiration.

Create tokens

Overview

To create a token you:

1. Determine the type of token you need.
2. Determine the object and its property values you want to tokenize, along with any special requirements for token expiration, etc.
3. Use the:
   • CLI create tokens command setting the --type flag to the token type chosen in step 1.
   • REST API tokenize operation setting the type property to the token type chosen in step 1.

Step-by-step

For example, you want to create a token that always returns the current email of a person in the buyers collection you created in Create a collection. To do this:

1. Determine the type token, which as you always want the current value of the email is a pointer token.

2. Determine the ID of the object.

3. Create the pointer token using the CLI like this:

   pvault token create \
           --collection buyers \
           --object-id cc9a39c5-4734-4786-b317-e16705d5128f \
           --props email \
           --type pointer

   You get a response similar to this:

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

   Or using the REST API like this:

   curl -s -X POST \
           --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/tokens?reason=AppFunctionality' \
           -H 'Authorization: Bearer pvaultauth' \
           -H 'Content-Type: application/json' \
           -d '[{ "type": "pointer", "object": {"id": "cc9a39c5-4734-4786-b317-e16705d5128f"}, "props": ["email"] }]'

   You get a response similar to this:

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

If you repeat this process with --props phone_number, you receive a token for the phone number. However, if you were to request --props phone_number,email you get one token for both pieces of information.

Create format preserving tokens

Overview

The ID of a token is, by default, a UUID. However, you can choose the format of the token ID. A token with a specific ID format is a format-preserving token. Such tokens are useful where you expect the tokenized data to pass through systems that validate the format of data values. By using a format-preserving token you can ensure that the data passes validation.

Format-preserving tokens are generated using a template that may use one or more seed properties. For example, the ID for a token that preserves the primary account number (credit card number) is created from a seed primary account number by preserving the seed's first six and last four digits and randomizing the remaining digits.

For example, take a buyer with a credit card with the number 1234567890123456. Passing this number as the seed to the format-preserving token might result in a token ID of 1234565234903456.

However, the seed doesn't have to be the primary account number being tokenized. For example, if the buyer's record includes two credit card numbers:

• cc1 with the number 1234567890123456
• cc2 with the number 6543210987654321

You can tokenize cc1 using cc2 as the seed, resulting in a token ID similar to 6543215740894321 that, when detokenized, returns 1234567890123456.

To create a format-preserving token:

1. Determine the type of token you need.
2. Determine the object and its property value you want to tokenize.
3. Determine the format-preserving template you want to use and any special requirements for token expiration, etc.
4. Use the:
   • CLI create tokens command, setting --fptemplate to the name of the template you want to use and --fpprops to the properties to seed the token ID.
   • REST API tokenize operation, setting fptemplate to the name of the template you want to use and fpprops to the properties to seed the token ID.

Step-by-step

You create a log of transactions made by buyers and want to store the buyers’ credit card details on each log record and tokenize these details to keep them private. You want to make details of the log available for audit purposes but are aware that your auditors load it into their system and that system validates that the record has a valid credit card number. To ensure that the records validate correctly, you create a format-preserving token by applying the primary_account_number template to the credit card number.

To do this:

1. Determine the type of token you need. As you want the log for audit purposes, you choose the pci token type.

2. Determine the ID of the buyers making the transaction.

3. Determine the format-preserving template you want to use. In this case, the template for perserving credit card number format.

4. Create a format-preserving token of the credit card details using the CLI like this:

   pvault token create \
           --collection customers \
           --object-id 32077c80-3792-4a45-a957-e365bb1c9533 \
           --props cc_number \
           --type randomized  \
           --fptemplate primary_account_number \
           --fpprops cc_number

   You get a response similar to this:

   +------------------+
   |     token_id     |
   +------------------+
   | 4012880901471881 |
   +------------------+

   Or using the REST API like this:

   curl -s -X POST \
        --url 'http://localhost:8123/api/pvlt/1.0/data/collections/customers/tokens?reason=AppFunctionality' \
        -H 'Authorization: Bearer pvaultauth' \
        -H 'Content-Type: application/json' \
        -d '[{ "type": "randomized", "object": {"id": "32077c80-3792-4a45-a957-e365bb1c9533"}, "props" : ["cc_number"], "fptemplate":"primary_account_number","fpprops":["cc_number"] }]'

   You get a response similar to this:

   [{"token_id":"4012880901471881"}]

5. Now, you save this token ID onto the transaction log.

6. When you make the transaction log available to your auditor and it is loaded into their system, the records pass validation because they include a valid but anonymized credit card number.

note

The credit card number returned for the format-preserving token is generated at random. This generated number may represent a live credit card number.