Skip to main content
POST
/
identities
/
:id
/
tokenize
/
:field
curl -X POST https://YOUR_BLNK_INSTANCE_URL/identities/idt_1234567890/tokenize/email_address \
  -H "X-Blnk-Key: YOUR_API_KEY"

{
  "message": "Field tokenized successfully"
}
Tokenizes a specific field in an identity record to protect personally identifiable information (PII). The field value is encrypted using format-preserving encryption, which maintains the same character types as the original value.

​
Path Parameters

​
id
string
required
The unique identifier of the identity
​
field
string
required
The name of the field to tokenize. Must be one of the tokenizable fields.

​
Tokenizable Fields

Only the following fields can be tokenized:
  • first_name (or FirstName)
  • last_name (or LastName)
  • other_names (or OtherNames)
  • email_address (or EmailAddress)
  • phone_number (or PhoneNumber)
  • street (or Street)
  • post_code (or PostCode)
Field names are case-insensitive. Both first_name and FirstName are accepted.

​
Response

​
message
string
Success message confirming the field was tokenized
curl -X POST https://YOUR_BLNK_INSTANCE_URL/identities/idt_1234567890/tokenize/email_address \
  -H "X-Blnk-Key: YOUR_API_KEY"

{
  "message": "Field tokenized successfully"
}

​
How Tokenization Works

​
Format-Preserving Encryption

Blnk uses format-preserving tokenization (FPT) that maintains the character types of the original value: Original Value: [email protected] Tokenized Value: FPT:[email protected]:aGVsbG8gd29ybGQ= The tokenized value consists of:
  1. FPT: - Prefix indicating format-preserving tokenization
  2. Format-preserving visible token - Maintains character types (letters, numbers, symbols)
  3. Encrypted original value - AES-256-GCM encrypted data

​
Character Type Preservation

  • Uppercase letters → Random uppercase letter
  • Lowercase letters → Random lowercase letter
  • Digits → Random digit
  • Special characters → Preserved as-is
  • Spaces → Preserved as-is

​
Security

Tokenization requires a 32-byte encryption key to be configured via BLNK_TOKENIZATION_SECRET environment variable or tokenization_secret in your blnk.json configuration file.
The encryption uses:
  • Algorithm: AES-256-GCM
  • Key derivation: HMAC-SHA256 for deterministic seeds
  • Uniqueness: Each tokenization produces a unique encrypted value

​
Tracking Tokenization

When a field is tokenized, the identity’s meta_data is automatically updated: 
{
  "meta_data": {
    "tokenized_fields": {
      "EmailAddress": true,
      "PhoneNumber": true
    }
  }
}
This allows you to track which fields are currently tokenized.

​
Use Cases

​
Compliance Requirements

Tokenize PII to comply with data protection regulations:
  • GDPR: Minimize exposure of personal data
  • PCI DSS: Protect cardholder information
  • HIPAA: Secure protected health information
  • CCPA: Reduce risk of data breaches

​
Data Access Control

Tokenize sensitive fields to:
  • Limit access to raw PII in databases
  • Allow analytics on tokenized data
  • Reduce the impact of data breaches
  • Enable secure data sharing with third parties

​
Audit and Compliance

Maintain compliance while:
  • Storing data in logs and backups
  • Sharing data with support teams
  • Exporting data for analysis
  • Archiving old records

​
Best Practices

  1. Tokenize Early: Tokenize PII as soon as it’s collected
  2. Selective Tokenization: Only tokenize fields that contain sensitive data
  3. Access Control: Limit access to detokenization endpoints
  4. Audit Trail: Log all tokenization and detokenization operations
  5. Key Management: Securely store and rotate encryption keys
  6. Backup Keys: Ensure encryption keys are backed up securely
Important: Once a field is tokenized, the original value is encrypted and can only be retrieved using the detokenize endpoint. Ensure your encryption key is securely backed up.

​
Error Handling

Common errors and their meanings:
ErrorCauseSolution
”field X is not tokenizable”Field is not in the allowed listUse one of the tokenizable fields listed above
”field X is already tokenized”Field has already been tokenizedUse detokenize first, then re-tokenize if needed
”tokenization is disabled”Encryption key not configuredSet BLNK_TOKENIZATION_SECRET environment variable
”identity not found”Invalid identity IDVerify the identity ID exists
See Also: Tokenize Multiple Fields, Detokenize Field, Get Tokenized Fields

Build docs developers (and LLMs) love

Get started for freeTalk to us