Detokenize

The detokenize endpoint enables you to detokenize tokens in order to retrieve their original values. This endpoint accepts an arbitrary JSON payload containing one or more Detokenization Expressions.

The maximum number of detokenization expressions within a single request is defined by your Tenant's "Detokenize Limit" Quota.

POST

https://api.basistheory.com/detokenize

Permissions

token:read

The token:read permission must be granted on the container of each token included in the request.

Detokenize a single token

This example uses a data-only expression to access the data of token 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb, then applies the json path expression $.number to retrieve the number field from the token's data.

Request

cURL

curl "https://api.basistheory.com/detokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "card_number": "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}"
}'

Node

await client.tokens.detokenize({
    "card_number": "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}"
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const token = await bt.detokenize({
  card_number: "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}",
});

C#

await client.Tokens.DetokenizeAsync(new
  {
    card_number = "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}"
  });

Java

Object detokenizedData = new TokensClient(ClientOptions.builder().build())
    .detokenize(new HashMap<String, String>() {{
        put("card_number", "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}");
    }});

Python

client.tokens.detokenize(
    request={
        "card_number": "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}"
    }
)

Go

result, err := client.Tokens.Detokenize(ctx, map[string]interface{}{
    "card_number": "{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb | json: '$.number' }}",
})

Response

{
  "card_number": "4242"
}

Detokenize a list of tokens

This example uses two full token expressions of the form {{ token: * }} to retrieve all the attributes on the tokens 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb and a1883f97-2e4c-439a-bf73-dffb681de929.

Request

cURL

curl "https://api.basistheory.com/detokenize" \
-H "BT-API-KEY: <API_KEY>" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
  "tokens": [
      "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}",
      "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929 }}"
  ],
}'

Node

await client.tokens.detokenize({
 "tokens":[
   '{{ 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}',
   '{{ a1883f97-2e4c-439a-bf73-dffb681de929 }}',
 ]
});

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

    const token = await bt.detokenize({
      tokens: [
      "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}",
      "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929 }}"
      ],
    });

C#

await client.Tokens.DetokenizeAsync(new
{
    tokens = new []
    {
        "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}",
        "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929 }}"
    }
});

Java

Object detokenizedData = new TokensClient(ClientOptions.builder().build())
    .detokenize(new HashMap<String, Object>() {{
        put("tokens", Arrays.asList(
            "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}",
            "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929 }}"
        ));
    }});

Python

client.tokens.detokenize(
    request={
        "tokens": [
            "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb  }}",
            "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929  }}",
        ]
    }
)

Go

result, err := client.Tokens.Detokenize(ctx, map[string]interface{}{
    "tokens": []string{
        "{{ token: 7993dbd8-19d5-44bf-b6dc-078e8b44c6cb }}",
        "{{ token: a1883f97-2e4c-439a-bf73-dffb681de929 }}",
    },
})

Response

{
  "tokens": [
    {
      "id": "7993dbd8-19d5-44bf-b6dc-078e8b44c6cb",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "secret data",
      "containers": ["/general/high/"],
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    },
    {
      "id": "a1883f97-2e4c-439a-bf73-dffb681de929",
      "type": "token",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "data": "secret data 2",
      "containers": ["/general/high/"],
      "metadata": {
        "nonSensitiveField": "Non-Sensitive Value 2"
      },
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2021-03-01T08:23:14+00:00"
    }
  ]
}