Skip to main content

Aliasing

By default, when creating a token, a random ID (v4 UUID) will be generated to represent the token and its secure payload. Token IDs can be safely stored within your system or transmitted within API requests without the risk of revealing sensitive information.

While randomly generated IDs may be sufficient for many use cases, there are several scenarios in which it can be valuable for a generated token ID to satisfy a specific format, or to allow a custom token ID to be specified within the request:

  • You would like the ID to resemble the format of the underlying token data (e.g. to satisfy validation constraints)
  • Due to technical constraints, your system requires the token ID to have a prescribed size or format (e.g. to store the ID within a legacy database column having a certain data type)
  • You wish to pre-generate token IDs within your system
  • You wish to define your own custom algorithm for generating token IDs

Basis Theory supports these use cases in two ways:

  1. Accepting a predefined token id when creating a token
  2. Specifying how an ID should be generated through the use of Alias Expressions

Predefined Token IDs​

A token ID can be pre-generated by your system and provided when creating a token within the id property. Any non-empty string value between 3 and 400 characters can be specified as an ID, as long as there is not another token within your tenant with the same ID. If a duplicate ID is found, a 409 CONFLICT response will be returned.

Alias Expressions​

Alias expressions allow you to leverage the full expression language to specify a token's ID via a dynamically evaluated expression, and can be provided within the id property of the create token or tokenize requests.

You are able to reference the data property within an object expression - data will be bound to the provided token data.

Typically, alias expressions are used in conjunction with one of the alias_* filters (e.g. alias_preserve_format or alias_preserve_length). These filters randomly generate a secure pseudonym based on the token's data. For example, if a token contains the credit card number 4242-4242-4242-4242, the alias expression {{ data | alias_preserve_format: 0, 4 }} could be used to reveal the last 4 digits in the ID while replacing all the other non-revealed digits with random digits, resulting in an ID of the form 9326-7128-4203-4242.

The number of randomly generated aliases satisfying a certain format is finite and has a chance to become exhausted. If a unique alias cannot be generated, a randomly generated UUID will be returned instead.

Best Practices​

While you have the ability to set any value as a token's ID, you should never reveal sensitive information in IDs. The id property will not be encrypted and will be revealed in plaintext within API requests and responses, and this value will likely be referenced within your systems.

Only reveal characters at the beginning or end of your token data if absolutely necessary, and if so, reveal the minimum number of characters possible. Every revealed character makes it easier for a malicious actor to try to uncover the underlying token's data. For example, given a 16 digit credit card number, revealing the first 6 and last 4 characters in a format preserving alias only leaves 6 remaining digits (10^6 = 1 million possible combinations), which can be reduced further knowing that the card number must have a valid Luhn checksum. Instead, consider revealing only the first 6 or last 4 digits, but not both.

Limitations​

Token IDs may not contain any of the following special characters: #, /, \, +, ?, [, ], |, &, =, %, <, >, {, }, ^

Including any restricted special characters in an ID will result in a 400 BAD REQUEST response.

Since token IDs are included within the URL route on some operations, some allowable special characters and whitespace characters will need to be URL encoded within requests where the ID is provided within the API route. The latest official Basis Theory SDKs automatically URL encode token IDs when they are included in the URL.

Examples​

SSN with Last 4 Digits Preserved​

Request
{
  "id": "{{ data | alias_preserve_format: 0, 4 }}",
  "type": "token",
  "data": "111-22-3333"
}

Example ID Value: 830-46-3333

Card Number with Last 4 Digits Preserved​

Request
{
  "id": "{{ data.number | alias_preserve_format: 0, 4 }}",
  "type": "card",
  "data": {
    "number": "4242424242424242",
    "expiration_month": 3,
    "expiration_year": 2025,
    "cvc": "456"
  }
}

Example ID Value: 9273610263384242

Email with Domain Preserved​

This example assumes you do not know the length of the email domain, and want to preserve arbitrary domains.

Request
{
  "id": "{{ data.email | split: '@' | first | alias_preserve_length }}@{{ data.email | split: '@' | last }}",
  "type": "token",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@gmail.com"
  }
}

Example ID Value: k7dn59wb@gmail.com

If you know the length of the domain ahead of time, you can simplify this expression by revealing the number of characters in the domain, e.g. {{ data.email | alias_preserve_length: 0, 10 }}.