Tokenization

Detokenize data

Detokenization involves using tokens to fetch sensitive data stored in a vault. Detokenization lets authorized users and processes access the original information whenever necessary. You can call the Detokenize API or use an SDK to detokenize your data and ensure data accessibility while abiding by security protocols.

Prerequisites

  • A vault for which you have the Vault Owner role.

  • Skyflow account, vault, and workspace details:

    1. In Studio, click vault menu icon > View vault details.
    2. Note your Account ID, Vault ID, and Vault URL values.

  • A bearer token to authenticate API calls. For a short-lived token, use the following process. To generate tokens from service accounts, see Authenticate.

    1. In Studio, click your account icon and choose Generate API Bearer Token.

    2. Click Generate Token.

  • Set environment variables for your account and vault details:

$export VAULT_URL=$VAULT_URL
$export VAULT_ID=$VAULT_ID
$export ACCOUNT_ID=$ACCOUNT_ID
$export BEARER_TOKEN=$BEARER_TOKEN
$export TOKEN_1=$TOKEN_VALUE_1
$export TOKEN_2=$TOKEN_VALUE_2
$export TOKEN_3=$TOKEN_VALUE_3
$export REDACTION_1=$REDACTION_TYPE_1
$export REDACTION_2=$REDACTION_TYPE_2
$export REDACTION_3=$REDACTION_TYPE_3

Detokenize your data

When you need to view sensitive, tokenized data, call the Detokenize API to retrieve the corresponding values.

$curl -s -X POST "$VAULT_URL/v1/vaults/$VAULT_ID/detokenize" \
>-H "Authorization: Bearer $BEARER_TOKEN" \
>-H "content-type: application/json" \
>-d '{
>    "detokenizationParameters": [
>      {
>        "token": "'"$TOKEN_VALUE_1"'",
>        "redaction": "$REDACTION_TYPE_1"
>      },
>      {
>        "token": "'"$TOKEN_VALUE_2"'",
>        "redaction": "$REDACTION_TYPE_2"
>      },
>      {
>        "token": "'"$TOKEN_VALUE_3"'",
>        "redaction": "$REDACTION_TYPE_3"
>      }
>    ],
>    "downloadURL": false
>}'

The response returns the detokenized values.

1{
2  "records": [
3    {
4      "token": "TOKEN_VALUE_1",
5      "valueType": "VALUE_TYPE",
6      "value": "DATA_VALUE"
7    },
8    {
9      "token": "TOKEN_VALUE_2",
10      "valueType": "VALUE_TYPE",
11      "value": "DATA_VALUE"
12    },
13    {
14      "token": "TOKEN_VALUE_3",
15      "valueType": "VALUE_TYPE",
16      "value": "DATA_VALUE"
17    }
18  ]
19}

Handle errors in batch operations

The continueOnError setting lets you manage the behavior of detokenization calls in the event of an error. When continueOnError is true, detokenization continues for all specified tokens even if the vault fails to find a value for a particular token. If false and any token in the request encounters an error, the request stops and returns an error message.

$curl -s -X POST "$MANAGEMENT_URL/v1/vaults/$VAULT_ID/detokenize" \
>-H "Authorization: Bearer $BEARER_TOKEN" \
>-H "content-type: application/json" \
>-d '{
>    "detokenizationParameters": [
>      {
>        "token": "'"$TOKEN_VALUE_1"'",
>        "redaction": "$REDACTION_TYPE_1"
>      },
>      {
>        "token": "'"$TOKEN_VALUE_2"'",
>        "redaction": "$REDACTION_TYPE_2"
>      },
>      {
>        "token": "'"$TOKEN_VALUE_3"'",
>        "redaction": "$REDACTION_TYPE_3"
>      }
>    ],
>    "downloadURL": false
>    "continueOnError": true
>}'

If the request is successful, the error field returns null. If it’s unsuccessful, valueType is NONE, and error displays a specific error message.

1{
2  "records": [
3    {
4      "token": "TOKEN_VALUE_1",
5      "valueType": "VALUE_TYPE",
6      "value": "DATA_VALUE",
7      "error": null
8    },
9    {
10      "token": "TOKEN_VALUE_2",
11      "valueType": "NONE",
12      "value": "",
13      "error": "Token not found"
14    },
15    {
16      "token": "TOKEN_VALUE_3",
17      "valueType": "VALUE_TYPE",
18      "value": "",
19      "error": "Token not found"
20    }
21  ]
22}

When continueOnError is false and token values are missing, the response returns an error message specifying the missing tokens.

1{
2  "error": {
3    "grpc_code": 5,
4    "http_code": 404,
5    "message": "Token not found for token_2, token_3",
6    "http_status": "Not Found",
7    "details": []
8  }
9}

Next steps

Learn more about tokenization, review tokenization and compliance, or explore data governance.