search

Tokenization APIs

This guide explains how to tokenize your data using a Skyflow vault. By the end of this guide, you’ll have successfully used Skyflow’s APIs to fetch tokens and swap tokens for the original data.

Prerequisites

Before you start,

    Log in to your Skyflow account. If you don’t have an account, you can sign up for a free trial account.
      For trial accounts, log in to try.skyflow.com. For production accounts, log in to your dedicated sign in URL.
    Complete the following guides:

Overview

Tokenizing data with Skyflow consists of three steps:

    Configure a vaultTokenize dataDetokenize data

In this guide, we’ll use the Quickstart vault.

Configure your vault

The credit_cards table in the Quickstart vault is pre-configured with four columns: cardholder_name, card_number, exp_month, and exp_year.

This vault is also pre-configured with the tokenization settings you need for each column.

    The cardholder_name, exp_month, and exp_year columns will generate UUID deterministic tokens. The card_number will generate format preserving deterministic tokens.

Tokenization option

Description

Example

UUID DETERMINISTIC TOKEN

The tokens for data in this column will be random UUIDs. The same raw value inserted multiple times will always be assigned the same token.

UUID TOKEN

The tokens for data in this column will be random UUIDs.

johndoe@acme.com”→ “c7db3f3a-5d01-4a98-961e-9cbdb6241b0d”

FORMAT PRESERVING DETERMINISTIC TOKEN

The tokens for data in this column will be random but format preserving based on the regex structure specified. However, the same raw value inserted multiple times will always be assigned the same token.

FORMAT PRESERVING TOKEN

The tokens for data in this column will be random, but they will also be format preserving based on the regex structure specified.

johndoe@acme.com”→ “bwe09f@fg7d8.com

Continue to the next step to retrieve the tokens.

Tokenize data

Once your vault has been configured, tokens will be automatically generated as soon as data is inserted. There are two ways to retrieve these tokens:

    Insert Record API: Use this API to get tokens for records when inserting them into the vault.Get Record API: Use this API to get tokens for records that are already in the vault.

Insert Record API

You can generate tokens upon inserting data in the vault.

    Use the Insert Record API with the tokenization parameter set to true in the body of the request as shown below.

    infoIf you're following along with a vault other than the Quickstart vault, keep in mind that the fields in the example code may differ slightly from what you would use.
    curl -i -X POST '$VAULT_URL/v1/vaults/$VAULT_ID/credit_cards' \
    -H 'Authorization: Bearer $BEARER_TOKEN' \
    -d '{
        "tokenization": true,
        "records": [
            {
                "fields": {
                    "cardholder_name" : "John Doe",
                    "card_number" : "4111111111111111",
                    "exp_date" : "11",
                    "exp_year" : "2025"
                }
            }
        ]
    }'

    Replace the VAULT_URL, VAULT_ID, and BEARER_TOKEN parameters. You can find the Vault URL and Vault ID by clicking the vault menu icon > Edit vault details as shown below.

    infoRefer to the API Authentication guide for help generating an API bearer token.

    vault_details_and_id

    The response should look similar to the following:

    {
        "records": [
            {
                "skyflow_id": "543b3500-200f-44b4-a336-b286bc3a68b0",
                "tokens": {
                    "card_number": "8493-8940-9501-8968",
                    "cardholder_name": "80ecd7d2-8d2a-496e-b749-4bb815c7a05b",
                    "exp_month": "34cb211c-63c5-4b0f-905e-b30e9d0a1228",
                    "exp_year": "d461dfeb-0e3d-4936-bdbf-a81c12ea99b7"
                }
            }
        ]
    }

    For the Quickstart vault, notice that the token for card_number is different than for the other fields. This is because the card_number field is configured to generate format preserving deterministic tokens. So the tokens have been configured to maintain the 16-digit credit card number format.

Get Record API

You can also get tokens for data that is already in the vault at any time.

    Use the Get Record API with the tokenization query parameter set to true as shown below.

    curl -i -X GET '$VAULT_URL/v1/vaults/$VAULT_ID/credit_cards/$SKYFLOW_ID?tokenization=true' \
    -H 'Authorization: Bearer $BEARER_TOKEN'

    Replace the VAULT_URL, VAULT_ID, SKYFLOW_ID, and BEARER_TOKEN parameters as demonstrated above in the Insert Record API section.

    Instead of the original values, tokens will be returned. The response should look similar to the following:

    {
        "fields": {
            "card_number": "8493-8940-9501-8968",
            "cardholder_name": "80ecd7d2-8d2a-496e-b749-4bb815c7a05b",
            "exp_month": "34cb211c-63c5-4b0f-905e-b30e9d0a1228",
            "exp_year": "d461dfeb-0e3d-4936-bdbf-a81c12ea99b7"
        }
    }

Detokenize data

You can exchange or “detokenize” your tokens for the original values at any time with the Detokenize API.

    Use the Detokenize API in the request body to pass in a list of tokens to be detokenized as shown below.

    curl -i -X POST '$VAULT_URL/v1/vaults/$VAULT_ID/detokenize' \
    -H 'Authorization: Bearer $BEARER_TOKEN' \
    -d '{
        "detokenizationParameters": [
            {
                "token": "80ecd7d2-8d2a-496e-b749-4bb815c7a05b"
            },
            {
                "token": "8493-8940-9501-8968"
            },
            {
                "token": "34cb211c-63c5-4b0f-905e-b30e9d0a1228"
            },
            {
                "token": "d461dfeb-0e3d-4936-bdbf-a81c12ea99b7"
            }
        ]
    }'

    Replace the VAULT_URL, VAULT_ID, and BEARER_TOKEN parameters.

    Replace the tokens with tokens from your own vault.

    The response should look similar to the following:

    {
        "records": [
            {
                "token": "80ecd7d2-8d2a-496e-b749-4bb815c7a05b",
                "valueType": "STRING",
                "value": "John Doe"
            },
            {
                "token": "8493-8940-9501-8968",
                "valueType": "STRING",
                "value": "4111111111111111"
            },
            {
                "token": "34cb211c-63c5-4b0f-905e-b30e9d0a1228",
                "valueType": "STRING",
                "value": "11"
            },
            {
                "token": "d461dfeb-0e3d-4936-bdbf-a81c12ea99b7",
                "valueType": "STRING",
                "value": "2025"
            }
        ]
    }

Next steps

You're ready to tokenize and detokenize sensitive data in a secure vault.

As next steps, check out the other Data APIs or one of the articles below:

In this article