Tokenization

Businesses often want to reduce their compliance scope, such as in PCI compliance, by limiting the number of places where sensitive data interacts with their backend systems. Skyflow can help you accomplish this using tokenization. Tokenization is a design pattern in which sensitive data is swapped for tokens, or random ciphertext. This guide will help you implement this design pattern in your own application. By the end of this guide, you will have:

  • Learned about tokenization and its benefits
  • Inserted sensitive data (a credit card number) into a vault in exchange for a token
  • Swapped the token back for a plain text value

Before you begin

How tokenization works

Tokenization is a design scheme to protect sensitive data in a store. Sensitive data is encrypted, then swapped with tokens (undecipherable ciphertext). When you store sensitive data in Skyflow, the platform returns tokens for each piece of data stored. When you need the real values, the provided tokens are swapped for encrypted values stored in the Skyflow vault, through secure APIs. There are three steps in the tokenization flow:

  1. Insert sensitive data into a Skyflow vault
  2. Generatetokens for the sensitive data and store them in your backend
  3. Retrieve the original data by swapping it for the token

Insert data into a vault

Start by inserting data into a Skyflow vault. The example below inserts a record into the Cards table in a Payments Vault.

Name Parameter Type Description
URL path (string) Your workspace URL. You can find this in your Vault Details page. It will be in this format:

https://{org-name}.{account-name}.vault.skyflowapis.com
VAULT_ID path (string) The vault ID. You can find this in your Vault Details page.
TABLE path (string) The name of the object (or table) into which you’d like to insert a new row or record. One of [cards, consumers, financialserviceproviders, merchants, credit_scores].
TOKEN header (string) An Bearer token. The request header value will be the string ‘Bearer’, followed by a space, followed by your token.
RECORDS body (JSON) The records to insert into the vault in JSON format.

Here’s a sample request for creating a fake record in the Cards table:

curl https://{URL}/v1/vaults/{VAULT_ID}/cards \
-X POST \
-H 'accept: application/json, text/plain, */*' \
-H 'content-type: application/json' \
-H 'authorization: Bearer {TOKEN}' \
--data-binary \
'{
  "records":[
    {
      "fields":{
        "type":"CREDIT",
        "network":"VISA",
        "card_number":"2034-3005-0884-8993",
        "cvv":"330"
      }
    }
  ]
}' 

Sample response:

{
  "records":[
    {
      "skyflow_id":"b79fc5bf-ff22-11ea-81ed-3a3117a4b7cd"
    }
  ]
}

Inserting a record returns a skyflow_id. Use this id to generate tokens for the fields within the record, as shown next:

Generate tokens for the data

To get tokens for the fields within a record, use the Get Record API with skyflow_id of the desired record and set the DLP Policy to ‘TOKEN’ as shown below:

Name Parameter Type Description
URL path (string) Your workspace URL. You can find this on your Vault Details page. It will be in this format:

https://{org-name}.{account-name}.vault.skyflowapis.com
VAULT_ID path (string) The vault ID. You can find this in your Vault Details page.
TABLE path (string) The name of the object (or table) into which you’d like to insert a new row or record. One of [cards, consumers, financialserviceproviders, merchants, credit_scores].
SKYFLOW_ID path (string) The skyflow_id of the customer record you would like to retrieve.
DLP query (string) The DLP policy to follow when retrieving the data. One of [DEFAULT, PLAIN_TEXT, TOKEN].
TOKEN header (string) A Bearer token. The request header value will be the string ‘Bearer’, followed by a space, followed by your token.

Here’s a sample request for getting a record from the Cards table with the ‘TOKEN’ DLP policy:

curl https://{URL}/v1/vaults/{VAULT_ID}/cards/{SKYFLOW_ID}?dlp=TOKEN \
-H 'accept: application/json, text/plain, */*' \
-H 'content-type: application/json' \
-H 'authorization: Bearer {TOKEN}' \

Sample response:

{
  "fields":{
    "skyflow_id":"b79fc5bf-ff22-11ea-81ed-3a3117a4b7cd",
    "type":"b79ffb1d-ff22-11ea-81ed-3a3117a4b7cd",
    "network":"b7a05e91-ff22-11ea-81ed-3a3117a4b7cd",
    "card_number":"b79ffb07-ff22-11ea-81ed-3a3117a4b7cd",
    "cvv":"b79ff045-ff22-11ea-81ed-3a3117a4b7cd",
  }
}

The response contains tokens for each field of the record you inserted. You can store these tokens in your backend systems.

Retrieve the original data in exchange for a token

When you need access to the original sensitive data, you can simply swap the token you stored for the real value using the tokens endpoint in the API. You can specify a DLP policy to apply to the result (‘default’ or ‘plain_text’) using the DLP query parameter. See Privacy Data Types for more information about DLP policies. Follow the examples below:

To retrieve the original data in exchange for a token, you’ll need to supply the parameters below:

Name Parameter Type Description
URL path (string) Your workspace URL. You can find this in your Vault Details page. It will be in this format:

https://{org-name}.{account-name}.vault.skyflowapis.com
VAULT_ID path (string) The vault ID. You can find this in your Vault Details page.
TOKEN path (string) The token to be exchanged for the original value.
DLP query (string) The DLP policy to follow when retrieving the data. One of [DEFAULT, PLAIN_TEXT].
BEARER header (string) A Bearer token. the request header value will be the string ‘Bearer’, followed by a space, followed by your token.

Here’s a sample request that retrieves the credit card number from its token using the default DLP policy:

curl https://{URL}/v1/vaults/{VAULT_ID}/tokens/b79ffb07-ff22-11ea-81ed-3a3117a4b7cd?dlp=DEFAULT \
-H 'accept: application/json, text/plain, */*' \
-H 'content-type: application/json' \
-H 'authorization: Bearer {BEARER}' \

Sample response:

{
  "fields":{
    "card_number":"*REDACTED*",
  }
}

Note that by default, sensitive fields like Credit Card Number will be redacted or masked. See Privacy Data Types for more information about DLP policies. To get the plain text value, follow the example below:

Here’s a sample request that retrieves the credit card number from its token using the plain text DLP policy:

curl https://{URL}/v1/vaults/{VAULT_ID}/tokens/b79ffb07-ff22-11ea-81ed-3a3117a4b7cd?dlp=PLAIN_TEXT \
-H 'accept: application/json, text/plain, */*' \
-H 'content-type: application/json' \
-H 'authorization: Bearer {BEARER}' \

Sample response:

{
  "fields":{
    "card_number":"2034-3005-0884-8993",
  }
}

Perform bulk tokenization operations

Skyflow also supports Bulk APIs for getting records (and their tokens) and swapping tokens. Bulk APIs allow for operations on a list of records in a single API call. They also have additional parameters that allow you to specify a subset of fields to be retrieved and to set the pagination for the number of records to be retrieved. Each table in Skyflow supports Bulk Get Records and Bulk Get Records by Token APIs. For the Cards table used in the previous example, see the Bulk Get Cards API and the Bulk Tokens API.