Skip to main content

Fingerprints

A fingerprint can be generated at the time a token is created, which can be used to uniquely identify the contents of a token. Fingerprints are cryptographically secure, protected against hash collision and preimage attacks, and cannot be reversed to recover the original token's data, so they are safe to store in your application and used to compare tokens without retrieving plaintext token data (e.g. for token deduplication).

Fingerprinting can either be globally enabled via the Fingerprint All Tokens tenant setting, or controlled on a per-token basis by disabling this setting. For new tenants, this setting defaults to false, and its value can be modified either through the Portal or through the tenant management API. Note that if this setting is enabled, there is no way to disable fingerprinting on a per-token basis.

Since fingerprinting performs a CPU-intensive cryptographic operation, creating tokens with fingerprints will increase the latency of each request. For this reason, we recommend that you leave the Fingerprint All Tokens setting disabled, and only enable fingerprinting on a per-token basis when it is necessary unless you need every new token to be fingerprinted.

When specifying a fingerprint expression during token creation, you may provide an expression that references the data and metadata variable within an object expression - data and metadata will be bound to the provided token data and metadata, respectively.

Token fingerprints are unique per tenant and token type, so you will get different fingerprints when tokenizing the same data across different token types, or across different tenants.

Examples​

Fingerprinting Primitive Tokens​

Request
{
  "type": "token",
  "data": "111-22-3333",
  "fingerprint_expression": "{{ data }}"
}

Fingerprinted Value: "111-22-3333"

Fingerprinting a Property of a Complex Token​

Request
{
  "type": "token",
  "data": {
    "bank": {
      "routing_number": "021000021",
      "account_number": "1234567890",
      "account_owner": {
        "first_name": "John",
        "middle_name": "Andrew",
        "last_name": "Smith"
      }
    }
  },
  "fingerprint_expression": "{{ data.bank.account_number }}"
}

Fingerprinted Value: "1234567890"

Fingerprinting Multiple Properties of a Complex Token​

Request
{
  "type": "token",
  "data": {
    "bank": {
      "routing_number": "021000021",
      "account_number": "1234567890",
      "account_owner": {
        "first_name": "John",
        "middle_name": "Andrew",
        "last_name": "Smith"
      }
    }
  },
  "fingerprint_expression": "{{ data.bank.routing_number }}|{{ data.bank.account_number }}"
}

Fingerprinted Value: "021000021|1234567890"

Transforming Data Before Fingerprinting​

Request
{
  "type": "token",
  "data": {
    "name": {
      "first_name": "John",
      "middle_name": "Andrew",
      "last_name": "Smith"
    }
  },
  "fingerprint_expression": "{{ data.name.first_name | upcase }} {{ data.last_name | upcase }}"
}

Fingerprinted Value: "JOHN SMITH"