Systems Integrator Guide

Reference Architecture

A complete identity tokenization system comprises several core components:

Figure 1: End-to-end tokenized identity data flow

Component Responsibilities

Token Lifecycle

Token Types

Identity Tokens

Long-lived references to identity records. Used for internal processing. Never shared directly with relying parties.

Sectoral Tokens

Derived from identity tokens using sector-specific keys. Shared with relying parties in specific sectors.

Session Tokens

Short-lived tokens for specific transactions. Include scope and expiry.

Consent Tokens (UCT)

Cryptographically signed authorization for specific data access.

Lifecycle Stages

1. Generation: Token created and mapping stored
2. Issuance: Token provided to authorized recipient
3. Validation: Token verified on each use
4. Refresh: New token issued before expiry (for session tokens)
5. Revocation: Token invalidated before natural expiry
6. Expiry: Token automatically becomes invalid

Figure 2: Consent issuance and verification sequence

API Patterns

Tokenization API

POST /v1/tokenize
Authorization: Bearer {service_token}
Content-Type: application/json

{
  "subject_reference": "uin:abc123",
  "token_type": "sectoral",
  "sector": "HEALTH",
  "ttl_seconds": 86400,
  "purpose": "patient_record_lookup"
}

Response:
{
  "token": "tok_h7k9m2n4p6q8r0s2",
  "expires_at": "2025-01-16T12:00:00Z",
  "sector": "HEALTH"
}

De-tokenization API

POST /v1/detokenize
Authorization: Bearer {service_token}
X-Consent-Token: {user_consent_token}
Content-Type: application/json

{
  "token": "tok_h7k9m2n4p6q8r0s2",
  "requested_attributes": ["given_name", "date_of_birth"]
}

Response:
{
  "attributes": {
    "given_name": "Jane",
    "date_of_birth": "1985-03-15"
  },
  "disclosure_id": "disc_x7y9z0"
}

Consent Validation API

POST /v1/consent/validate
Authorization: Bearer {service_token}
Content-Type: application/json

{
  "consent_token": "{UCT}",
  "requested_scopes": ["read:name", "read:dob"],
  "relying_party_id": "rp_bank_acme"
}

Response:
{
  "valid": true,
  "authorized_scopes": ["read:name", "read:dob"],
  "expires_at": "2025-01-16T12:00:00Z",
  "subject_token": "tok_subj_masked"
}

Key Management

Key Types

HSM Recommendations

• Store master keys and sectoral derivation keys in HSM
• Use HSM for cryptographic operations (derivation, signing)
• Implement key ceremonies for critical key generation
• Maintain offline backup of critical keys with split custody
• Log all HSM operations to tamper-evident audit log

Storage Patterns

Token Store Design

• Store token-to-reference mappings, not PII
• Include metadata: creation time, expiry, revocation status
• Index by token value for O(1) lookup
• Encrypt at rest with key from HSM
• Consider sharding for horizontal scalability

PII Vault Design

• Separate network segment with strict access controls
• Field-level encryption for sensitive attributes
• No direct access from application tier
• Access only through tokenization service with valid consent
• Regular access audits and anomaly detection

Audit Log Design

• Append-only storage (immutable)
• Cryptographic chaining or Merkle tree for tamper evidence
• Include: timestamp, operation, actor, subject token, purpose, outcome
• Separate write and read paths
• Long-term archival with integrity verification

Implementation Best Practices

Do

• Use scopes: Define granular scopes for each attribute or operation
• Bind to context: Include audience, purpose, and expiry in all tokens
• Validate on every use: Check consent validity before each disclosure
• Log comprehensively: Every tokenization and disclosure event
• Support revocation: Enable immediate consent and token revocation
• Use short-lived session tokens: Minimize window of exposure
• Implement rate limiting: Prevent enumeration and abuse
• Version your tokens: Include version for future format changes

Don't

• Don't use tokens as secrets: Tokens should be validated, not used as passwords
• Don't embed PII in tokens: Tokens should be opaque references
• Don't share sectoral keys: Each sector should have isolated derivation keys
• Don't skip consent validation: Always verify consent before de-tokenization
• Don't log PII: Audit logs should use tokens and references
• Don't cache de-tokenized data: Re-validate consent for each access
• Don't expose internal tokens: Use sectoral or session tokens externally

Security Considerations

Threat Modeling

Consider these attack vectors when designing:

Cryptographic Recommendations

• Token generation: CSPRNG with minimum 128 bits of entropy
• Sectoral derivation: HMAC-SHA256 or HKDF
• Signing: ECDSA P-256 or Ed25519
• Encryption at rest: AES-256-GCM
• TLS: 1.3 preferred, 1.2 minimum with strong cipher suites

Integration Patterns

API Gateway Integration

# Example: nginx configuration snippet
location /api/identity/ {
    # Validate JWT at gateway
    auth_jwt "Identity API";
    auth_jwt_key_file /etc/nginx/jwt_keys.json;

    # Forward consent token header
    proxy_set_header X-Consent-Token $http_x_consent_token;

    # Rate limiting
    limit_req zone=identity_api burst=10 nodelay;

    proxy_pass http://tokenization-service;
}

Event-Driven Integration

For asynchronous operations, publish events to message queues:

• identity.token.created - New token generated
• identity.token.revoked - Token invalidated
• consent.granted - User approved data sharing
• consent.revoked - User withdrew consent
• disclosure.completed - Data shared with relying party

Related Resources

• Architecture - Detailed system design
• Concepts - Foundational concepts explained
• Sources - Technical references and standards