How to Tokenize PII

This guide walks you through tokenizing PII data — from creating a policy to tokenizing values, detokenizing with a grant, and monitoring the process.

Prerequisites

• A slim.io account with at least one connected data source
• An API key (Settings → API Keys) or valid JWT session
• The slim-tokens SDK installed (optional but recommended)

# Python
pip install slim-tokens
 
# Node.js
npm install @slim-io/tokens

Step 1: Create a Tokenization Policy

A policy defines which PII types to tokenize, which encryption mode to use, and who can detokenize.

Via the Dashboard

1. Navigate to Tokenization → Token Policies
2. Click Create policy
3. Configure:
   • Name: Give the policy a descriptive name (e.g., “HIPAA SSN Protection”)
   • Type rules: Add rules for each PII type you want to tokenize
   • Mode: Choose deterministic (for joins), randomized (for max security), or format-preserving (for downstream validation)
   • Access control: Set allowed roles and purposes for detokenization
   • Failure policy: Choose fail-closed (default, recommended) or fail-open

Via the API

curl -X POST https://api.slim.io/api/v1/tokens/policies \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HIPAA SSN Protection",
    "type_rules": {
      "us_ssn": {
        "mode": "deterministic",
        "min_confidence": 0.85,
        "deterministic_scope": "global"
      },
      "email": {
        "mode": "deterministic",
        "min_confidence": 0.8
      }
    },
    "allowed_roles": ["admin", "privacy_officer"],
    "allowed_purposes": ["customer_support", "regulatory", "data_recovery"],
    "require_reason": true
  }'

Step 2: Tokenize Values

Via the SDK (recommended)

from slim_tokens import SlimTokens
 
client = SlimTokens(api_key="slim_...")
 
# Tokenize a batch of PII values
result = client.tokenize(
    items=[
        {"value": "123-45-6789", "pii_type": "us_ssn"},
        {"value": "john@example.com", "pii_type": "email"},
        {"value": "(555) 123-4567", "pii_type": "phone"},
    ],
    policy_id="pol_hipaa",
)
 
for item in result.results:
    print(f"{item.status}: {item.token_id} → {item.token}")

Via the API

curl -X POST https://api.slim.io/api/v1/tokens/tokenize \
  -H "X-API-Key: slim_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"value": "123-45-6789", "pii_type": "us_ssn"}
    ],
    "policy_id": "pol_hipaa"
  }'

Dry Run

Add ?dry_run=true to preview the results without writing to the vault:

curl -X POST "https://api.slim.io/api/v1/tokens/tokenize?dry_run=true" \
  -H "X-API-Key: slim_..." \
  -H "Content-Type: application/json" \
  -d '{ "items": [...], "policy_id": "pol_hipaa" }'

Step 3: Detokenize with a Grant

Detokenization requires a time-limited, single-use grant. This ensures every access is authorized and audited.

# Step 3a: Request a grant
grant = client.create_grant(
    token_ids=["tok_abc123"],
    purpose="customer_support",
    reason="Case #12345 — identity verification",
)
 
# Step 3b: Detokenize
plain = client.detokenize(
    tokens=["tok_abc123"],
    grant_jwt=grant.jwt,
)
print(plain.results[0].value)  # "123-45-6789"

Step 4: Monitor Tokenization

Token Vault

View all tokens in the vault at Tokenization → Token Vault. You can:

• Search by token ID or PII type
• Filter by status (active, revoked, expired)
• Revoke individual tokens

Audit Trail

View all detokenization events at Tokenization → Detokenize Audit:

• Who accessed which tokens
• Purpose and reason provided
• Whether access was granted or denied
• Timestamp and trace ID

Usage Dashboard

Check tokenization usage at Tokenization → Token Vault (KPI strip):

• Total tokens created
• Active vs. revoked vs. expired
• Operations this billing period

Best Practices

1. Start with deterministic mode if you need cross-system joins. Switch to randomized for highly sensitive data where joinability is not needed.

2. Always require a reason for detokenization (require_reason: true). This creates a clear audit trail for compliance.

3. Use format-preserving mode sparingly — only when downstream systems require the original format (e.g., a phone number field that validates format).

4. Set appropriate confidence thresholds. A min_confidence of 0.85 avoids tokenizing false-positive PII detections.

5. Test with dry run first. Use ?dry_run=true to preview which values would be tokenized before committing to the vault.

6. Revoke tokens instead of deleting them. Revoked tokens remain in the vault for audit purposes but cannot be detokenized.

Supported PII Types

Next Steps

• Tokenization API Reference — Full endpoint documentation
• Tokenization & Masking — Detailed feature guide
• Data Classification — How PII is detected and classified