Skip to main content

Token Associations

Token associations allow you to associate any two tokens, of any type, together. This allows you to create parent-child relationships between tokens and traverse between tokens.

Create Token Association

Create a new parent/child association between two tokens in the Tenants.

POST https://api.basistheory.com/tokens/{parent_id}/children/{child_id}
Copy

Permissions

token:read

Creating an association between two existing tokens requires read permission on both the parent and child tokens.

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children/c1e565009-1984-4638-8fca-dce8a82cc2af" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST"

URI Parameters

ParameterRequiredTypeDefaultDescription
parent_idtruestringnullThe ID of the parent token
child_idtruestringnullThe ID of the child token

Bi-directional associations can be made between two tokens by creating a token association and swapping the parent_id and child_id.

Response

Returns an error if the token association failed to create.

Delete Token Association

Delete a parent/child association between two tokens in the Tenant.

DELETE https://api.basistheory.com/tokens/{parent_id}/children/{child_id}
Copy

Permissions

token:delete

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children/c1e565009-1984-4638-8fca-dce8a82cc2af" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "DELETE"

URI Parameters

ParameterRequiredTypeDefaultDescription
parent_idtruestringnullThe ID of the parent token
child_idtruestringnullThe ID of the child token

Response

Returns an error if the token association failed to delete.

Create Child Token for a Token

Create a new child token a token in the Tenant.

POST https://api.basistheory.com/tokens/{parent_id}/children
Copy

Permissions

token:createtoken:read

Creating a child token requires the appropriate create permission to the child token and read permission to the parent token.

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED" \
-H "Content-Type: application/json" \
-X "POST" \
-d '{
"type": "token",
"data": "Sensitive Value",
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
}
}'

URI Parameters

ParameterRequiredTypeDefaultDescription
parent_idtruestringnullThe ID of the parent token

Request Parameters

See Create Token for supported request parameters.

Response

Returns a token if the child token was created for the parent token. Returns an error if there were validation errors, or the token failed to create.

{
"id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
"tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
"type": "token",
"containers": ["/general/high/"],
"created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
"created_at": "2020-09-15T15:53:00+00:00",
"metadata": {
"nonSensitiveField": "Non-Sensitive Value"
}
}

List Child Tokens for a Token

Get a list of child tokens for a token in the Tenant.

GET https://api.basistheory.com/tokens/{parent_id}/children
Copy

Permissions

token:read

Request

curl "https://api.basistheory.com/tokens/c06d0789-0a38-40be-b7cc-c28a718f76f1/children" \
-H "BT-API-KEY: key_N88mVGsp3sCXkykyN2EFED"

URI Parameters

ParameterRequiredTypeDefaultDescription
parent_idtruestringnullThe ID of the parent token

Query Parameters

ParameterRequiredTypeDefaultDescription
idfalsearray[]An optional list of token ID's to filter the list of child tokens by
typefalsearray[]An optional array of token types to filter the list of child tokens by

Response

Returns a paginated object with the data property containing an array of child tokens for the parent token. Providing any query parameters will filter the child tokens. Returns an error if tokens could not be retrieved.

{
"pagination": {...},
"data": [
{
"id": "c1e565009-1984-4638-8fca-dce8a82cc2af",
"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"
},
{...},
{...}
]
}