Designing APIs for Consent-Based Data Exchange

Data portability and consent-based sharing require APIs that support fine-grained authorization, audit trails, and interoperability. This article covers implementation patterns using OAuth 2.0, OpenID Connect, and consent receipts.

Consent as a First-Class Concept

Traditional APIs often treat authorization as binary. Consent-based systems need:

• Granular scope definition
• Revocability
• Auditability
• Cross-system interoperability

OAuth 2.0 and Scopes

Scope Design

# Read-only profile
scope=profile:read

# Specific data categories with expiry
scope=transactions:read:30d
scope=identity:verify

Consent Flow

1. Resource owner initiates data share
2. Authorization server presents scope request
3. User grants/denies with optional constraints
4. Consent receipt issued and stored

Consent Receipts

Machine-readable records of what was consented:

{
  "consent_id": "urn:uuid:...",
  "timestamp": "2024-06-15T10:00:00Z",
  "data_controller": "https://api.example.com",
  "purposes": ["account_aggregation"],
  "data_categories": ["transactions"],
  "retention": "P30D",
  "revocable": true
}

Store receipts for audit and to support revocation flows.

API Versioning for Interoperability

When multiple systems exchange data, versioning prevents breakage:

URL Versioning

GET /v2/accounts
Accept: application/vnd.api+json;version=2

Schema Evolution

• Add optional fields only
• Deprecate with sunset headers
• Maintain backward compatibility for N versions

Cross-Border Considerations

• Data residency requirements
• Jurisdiction-specific consent rules
• Encryption in transit (TLS 1.3)
• Audit log retention by region

Conclusion

Consent-based data exchange APIs require careful design for interoperability. OAuth scopes, consent receipts, and versioning form a practical foundation for systems that need to share data across organizational and geographic boundaries.