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.

{
  "records": [
    {
      "token": "TOKEN_VALUE_1",
      "valueType": "VALUE_TYPE",
      "value": "DATA_VALUE"
    },
    {
      "token": "TOKEN_VALUE_2",
      "valueType": "VALUE_TYPE",
      "value": "DATA_VALUE"
    },
    {
      "token": "TOKEN_VALUE_3",
      "valueType": "VALUE_TYPE",
      "value": "DATA_VALUE"
    }
  ]
}

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.

{
  "records": [
    {
      "token": "TOKEN_VALUE_1",
      "valueType": "VALUE_TYPE",
      "value": "DATA_VALUE",
      "error": null
    },
    {
      "token": "TOKEN_VALUE_2",
      "valueType": "NONE",
      "value": "",
      "error": "Token not found"
    },
    {
      "token": "TOKEN_VALUE_3",
      "valueType": "VALUE_TYPE",
      "value": "",
      "error": "Token not found"
    }
  ]
}

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

{
  "error": {
    "grpc_code": 5,
    "http_code": 404,
    "message": "Token not found for token_2, token_3",
    "http_status": "Not Found",
    "details": []
  }
}

Next steps

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