Detokenize Field

​

Path Parameters

​

Response

curl -X GET https://YOUR_BLNK_INSTANCE_URL/identities/idt_1234567890/detokenize/email_address \
  -H "X-Blnk-Key: YOUR_API_KEY"

{
  "field": "email_address",
  "value": "john.doe@example.com"
}

​

Security Considerations

​

Access Control Best Practices

1. Role-Based Access: Restrict this endpoint to specific roles (e.g., compliance officers, customer support with supervision)
2. Audit Logging: Log every detokenization request with:
   • User ID and role
   • Timestamp
   • Identity ID
   • Field name
   • IP address
   • Request context
3. Rate Limiting: Implement rate limits to prevent bulk detokenization
4. Multi-Factor Authentication: Require MFA for users with detokenization access
5. Time-Limited Access: Implement temporary access grants that expire
6. Justification Required: Require users to provide a reason for detokenization

​

Compliance Requirements

• GDPR: Document legitimate reasons for accessing personal data
• PCI DSS: Implement strong access controls and audit trails
• HIPAA: Maintain detailed access logs for PHI
• SOC 2: Demonstrate appropriate security controls

​

How Detokenization Works

​

Decryption Process

1. Retrieve Identity: Fetch the identity record from the database
2. Verify Tokenization: Check if the field is marked as tokenized in meta_data.tokenized_fields
3. Extract Token: Get the tokenized value from the specified field
4. Decrypt: Use AES-256-GCM to decrypt the token
5. Return Original: Return the original plain text value

​

Token Format Detection

• Format-Preserving Tokens: Start with FPT: prefix
• Standard Tokens: Base64-encoded encrypted values

​

Use Cases

​

Customer Support

// Support agent needs to verify customer email
GET /identities/idt_1234567890/detokenize/email_address

// Response
{
  "field": "email_address",
  "value": "john.doe@example.com"
}

​

Fraud Investigation

// Fraud team investigating suspicious activity
GET /identities/idt_suspicious123/detokenize/phone_number

// Response
{
  "field": "phone_number",
  "value": "+1234567890"
}

​

Compliance Audit

// Compliance officer verifying customer information
GET /identities/idt_audit456/detokenize/street

// Response
{
  "field": "street",
  "value": "123 Main Street, Apt 4B"
}

​

Error Handling

​

Field Not Tokenized

{
  "error": "field email_address is not tokenized. Metadata: {\"tokenized_fields\":{\"PhoneNumber\":true,\"Street\":true}}"
}

​

Field Name Variations

• email_address or EmailAddress
• phone_number or PhoneNumber
• first_name or FirstName

​

Performance Considerations

• Decryption Speed: Detokenization is fast (typically <10ms)
• Database Queries: Each request requires one database query to fetch the identity
• Rate Limiting: Consider implementing rate limits to prevent abuse
• Caching: Do not cache detokenized values - always retrieve on-demand

​

Monitoring and Alerts

• High Volume: Alert on unusual spikes in detokenization requests
• Failed Attempts: Track repeated failures (may indicate attacks)
• Unauthorized Access: Alert on access from unexpected IP addresses or users
• After-Hours Access: Flag detokenization outside business hours

​

Implementation Example

// Example with audit logging
async function detokenizeField(identityId, fieldName, userId, reason) {
  // Log the detokenization request
  await auditLog.create({
    action: 'DETOKENIZE_FIELD',
    userId: userId,
    identityId: identityId,
    fieldName: fieldName,
    reason: reason,
    timestamp: new Date(),
    ipAddress: request.ip
  });
  
  // Make the API request
  const response = await fetch(
    `https://YOUR_BLNK_INSTANCE_URL/identities/${identityId}/detokenize/${fieldName}`,
    {
      headers: {
        'X-Blnk-Key': 'YOUR_API_KEY'
      }
    }
  );
  
  const data = await response.json();
  
  // Alert security team for sensitive operations
  if (fieldName === 'email_address' || fieldName === 'phone_number') {
    await securityAlert.send({
      message: `User ${userId} detokenized ${fieldName} for identity ${identityId}`,
      severity: 'INFO'
    });
  }
  
  return data;
}