> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PII Tokenisation in Blnk
> Learn how to secure sensitive customer data using PII tokenization.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
Available in version 0.8.8 and later.
PII (Personally Identifiable Information) tokenization allows you to replace sensitive customer data with non-sensitive tokens while maintaining the ability to use the data for business operations.
By tokenizing PII within your identity records, you can enhance security, reduce compliance scope, and still maintain full functionality within your applications.
Blnk Ledger supports two types of tokenization:
1. **Standard Tokenization:** Replaces the original value with a completely random token.
2. **Format-Preserving Tokenization:** Creates a token that maintains the format and structure of the original data.
***
## Tokenizable fields
The following identity fields can be tokenized in Blnk Ledger:
* `FirstName`
* `LastName`
* `OtherNames`
* `EmailAddress`
* `PhoneNumber`
* `Street`
* `PostCode`
Identity JSON uses **snake\_case** (`first_name`, `email_address`). Tokenization paths and `fields` arrays use **PascalCase** (`FirstName`, `EmailAddress`). They are not interchangeable.
| Identity JSON field | Tokenization name |
| :------------------ | :---------------- |
| `first_name` | `FirstName` |
| `last_name` | `LastName` |
| `other_names` | `OtherNames` |
| `email_address` | `EmailAddress` |
| `phone_number` | `PhoneNumber` |
| `street` | `Street` |
| `post_code` | `PostCode` |
Use PascalCase in tokenize and detokenize URLs, and in the `fields` array for multi-field requests.
***
## Tokenize a specific field
To tokenize a specific field, use the [Tokenize Field](/reference/tokenize-field) endpoint:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}/tokenize/EmailAddress" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.tokenizeField(
'idt_3b63c8da-af29-4cc3-ad38-df17d87456e6',
'EmailAddress',
);
```
```json Response theme={"system"}
{
"message": "Field tokenized successfully"
}
```
***
## Tokenize multiple fields
To tokenize multiple fields in an identity at once, use the [Tokenize Identity](/reference/tokenize-identity) endpoint:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}/tokenize" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"fields": ["FirstName", "LastName", "EmailAddress", "PhoneNumber"]
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.tokenize(
'idt_3b63c8da-af29-4cc3-ad38-df17d87456e6',
{
fields: ['FirstName', 'LastName', 'EmailAddress', 'PhoneNumber'],
},
);
```
```json Response theme={"system"}
{
"message": "Fields tokenized successfully"
}
```
***
## View tokenized fields
To check which fields are currently tokenized for an identity, use the [Get Tokenized Fields](/reference/get-tokenized-fields) endpoint:
```bash cURL wrap theme={"system"}
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}/tokenized-fields" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.getTokenizedFields(
'idt_3b63c8da-af29-4cc3-ad38-df17d87456e6',
);
```
```json Response theme={"system"}
{
"tokenized_fields": ["FirstName", "LastName", "EmailAddress", "PhoneNumber"]
}
```
***
## Detokenize a specific field
To retrieve the original value of a tokenized field, use the [Detokenize Field](/reference/detokenize-field) endpoint:
```bash cURL wrap theme={"system"}
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}/detokenize/EmailAddress" \
-H "X-blnk-key: "
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.detokenizeField(
'idt_3b63c8da-af29-4cc3-ad38-df17d87456e6',
'EmailAddress',
);
```
```json Response theme={"system"}
{
"field": "EmailAddress",
"value": "alice.smith@example.com"
}
```
***
## Detokenize multiple fields
To retrieve the original values of multiple tokenized fields, use the [Detokenize Identity](/reference/detokenize-identity) endpoint:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}/detokenize" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"fields": ["FirstName", "LastName", "EmailAddress", "PhoneNumber"]
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.detokenize(
'idt_3b63c8da-af29-4cc3-ad38-df17d87456e6',
{
fields: ['FirstName', 'LastName', 'EmailAddress', 'PhoneNumber'],
},
);
```
```json Response theme={"system"}
{
"fields": {
"first_name": "Alice",
"last_name": "Smith",
"email_address": "alice.smith@example.com",
"phone_number": "+1234567890"
}
}
```
***
## Format-preserving tokenization example
When using format-preserving tokenization, the tokens maintain the same structure as the original data:
Original Email: `alice.smith@example.com`
Tokenized Email: `FPT:utlgv.jtwka@ifvnpgq.dfe:8jygO668erXz6F+2sQbaGh3StrdkiI7++8nthzFzk7lVtPtZqNgscpsUDWav9jYv4J8x`
The tokenized value preserves the email format while securing the actual content. This allows systems that rely on email formatting to continue functioning properly with tokenized data.
***
## Error handling
Structured errors are available from Blnk Core 0.15.0 and later.
Tokenization requests can return `400 Bad Request`, `403 Forbidden`, or `409 Conflict` depending on the field state and server configuration.
| Code | When it happens |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `IDT_FIELD_NOT_TOKENIZABLE` | Field name is wrong or not in the [tokenizable set](#tokenizable-fields). **Wrong casing is a common cause** - `first_name` returns this code even though `FirstName` is tokenizable. |
| `IDT_FIELD_ALREADY_TOKENIZED` | You tokenize a field that is already tokenized |
| `IDT_FIELD_NOT_TOKENIZED` | You detokenize a field that is not tokenized |
| `IDT_TOKENIZATION_DISABLED` | Tokenization is not configured on the server |
```json 400 Bad Request wrap theme={"system"}
{
"error": "field first_name is not tokenizable",
"error_detail": {
"code": "IDT_FIELD_NOT_TOKENIZABLE",
"message": "field first_name is not tokenizable",
"details": {}
}
}
```
To resolve the error:
| Code | What to do |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `IDT_FIELD_NOT_TOKENIZABLE` | Use the PascalCase name from the [mapping table](#tokenizable-fields). For example, tokenize `/tokenize/FirstName`, not `/tokenize/first_name`. |
| `IDT_FIELD_ALREADY_TOKENIZED` | Skip tokenization or detokenize the field first if you need to replace the value |
| `IDT_FIELD_NOT_TOKENIZED` | Tokenize the field before calling detokenize |
| `IDT_TOKENIZATION_DISABLED` | Configure `tokenization_secret` on your Blnk Core instance |
For the full error catalogue, see [API error codes](/advanced/error-codes).
***
## Why use PII tokenization?
1. **Enhanced Security:**
**Reduced risk exposure**: Sensitive data is removed from your systems and replaced with tokens.
**Breach protection**: Even if tokens are compromised, they cannot be reversed to obtain the original data without access to the tokenization system.
2. **Simplified Compliance:**
**Reduced PCI DSS scope**: By tokenizing payment information, you can reduce the scope of compliance requirements.
**GDPR and data privacy**: Helps meet data minimization requirements by limiting where actual PII is stored.
3. **Data Usability:**
**Maintain functionality**: Systems can continue to process tokenized data without modification.
**Format preservation**: Tokens can maintain the format of the original data, ensuring compatibility with existing systems.
4. **Audit and Access Control:**
**Granular permissions**: Control which users and systems can detokenize specific fields.
**Comprehensive audit trails**: All tokenization and detokenization events are logged for security monitoring.
***
## Best practices
1. **Only detokenize when necessary:** Keep data in tokenized form whenever possible
2. **Implement proper access controls:** Restrict detokenization capabilities to authorized users only
3. **Use format-preserving tokens:** When systems require specific data formats, use format-preserving tokenization
4. **Regular security reviews:** Periodically review tokenization practices and access patterns
***
## Need help?
We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.
To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.