| name | privacy-api-design |
| description | Design privacy API patterns including data subject API for DSAR endpoints, consent API for preference management, deletion API with cascading delete orchestration, and audit API for compliance reporting. Provides OpenAPI specifications, error handling, rate limiting, and authentication patterns. |
| license | Apache-2.0 |
| metadata | {"author":"mukul975","version":"1.0","domain":"privacy","subdomain":"privacy-engineering","tags":"privacy-api, dsar-api, consent-api, deletion-api, openapi-specification"} |
Privacy API Design Patterns
Overview
Privacy APIs provide programmatic interfaces for data subject rights exercise, consent management, data deletion, and audit logging. Well-designed privacy APIs enable organizations to automate compliance workflows, integrate with consent management platforms, and provide data subjects with self-service privacy controls. This skill covers API design patterns, OpenAPI specifications, authentication, and error handling for privacy-critical endpoints.
API Architecture Overview
External Consumers Privacy API Gateway Backend Services
+------------------+ +--------------------+ +------------------+
| Data Subject App |----HTTPS/TLS--->| Authentication | | DSAR Service |
+------------------+ | Rate Limiting |----internal---->| Consent Service |
| Request Validation | | Deletion Service |
+------------------+ | Audit Logging | | Audit Service |
| Partner Portal |----HTTPS/TLS--->| Versioning | | Identity Service |
+------------------+ +--------------------+ +------------------+
|
+------------------+ v
| Internal Systems |----mTLS-------->+--------------------+
+------------------+ | Privacy Event Bus |
| (async processing) |
+--------------------+
1. Data Subject API (DSAR Endpoints)
OpenAPI Specification
openapi: 3.1.0
info:
title: Cipher Engineering Labs - Data Subject Rights API
version: 1.0.0
description: >
API for data subjects to exercise their privacy rights under GDPR,
CCPA/CPRA, and other applicable privacy regulations.
contact:
name: Privacy Engineering Team
email: privacy-engineering@cipherengineeringlabs.com
servers:
- url: https://api.cipherengineeringlabs.com/privacy/v1
description: Production
security:
- BearerAuth: []
- OAuth2: [dsar:read, dsar:write]
paths:
/dsar/requests:
post:
operationId: createDSARRequest
summary: Submit a new data subject access request
tags: [DSAR]
requestBody:
[]
[, , , ]
[, , , , , ]
[]
[]
[, , , , , ]
[, , ]
[]
[, , , , , ]
[, , ]
[, , , , ]
2. Consent API
Consent Preference Management
paths:
/consent/preferences:
get:
operationId: getConsentPreferences
summary: Get current consent preferences for the authenticated user
tags: [Consent]
responses:
'200':
description: Current consent preferences
content:
application/json:
schema:
type: object
properties:
subjectId:
type: string
preferences:
type: array
items:
$ref: '#/components/schemas/ConsentPreference'
lastUpdated:
type: string
format: date-time
put:
operationId: updateConsentPreferences
summary: Update consent preferences (bulk update)
[]
[]
[, ]
[, , , , ]
[]
[, , , ]
[]
3. Deletion API
Cascading Delete Orchestration
"""
Privacy deletion API with cascading delete orchestration.
Handles deletion requests across multiple backend services
with verification and audit logging.
"""
from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum
from typing import Optional
import uuid
class DeletionStatus(Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
PARTIALLY_COMPLETED = "partially_completed"
COMPLETED = "completed"
FAILED = "failed"
VERIFIED = "verified"
class ServiceDeletionStatus(Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
FAILED = "failed"
SKIPPED = "skipped"
@dataclass
class DeletionTarget:
service_name: str
data_categories: list[str]
priority: int
legal_hold_check: bool = True
retention_exempt: bool = False
@dataclass
class ServiceDeletionResult:
service_name:
status: ServiceDeletionStatus
records_deleted:
records_retained:
retention_reason: []
completed_at: [datetime]
error_message: []
:
request_id:
subject_id:
status: DeletionStatus
created_at: datetime
scope: []
exclude: []
service_results: [ServiceDeletionResult] = field(default_factory=)
verified_at: [datetime] =
verification_method: [] =
:
():
.targets = (service_registry, key= t: t.priority)
.audit = audit_logger
() -> DeletionRequest:
exclude = exclude []
request = DeletionRequest(
request_id=(uuid.uuid4()),
subject_id=subject_id,
status=DeletionStatus.IN_PROGRESS,
created_at=datetime.now(timezone.utc),
scope=scope,
exclude=exclude
)
.audit.log_deletion_start(request)
target .targets:
scope:
relevant_categories = (target.data_categories) & (scope)
relevant_categories:
(target.data_categories) & (exclude):
result = ServiceDeletionResult(
service_name=target.service_name,
status=ServiceDeletionStatus.SKIPPED,
records_deleted=,
records_retained=,
retention_reason=,
completed_at=datetime.now(timezone.utc),
error_message=
)
request.service_results.append(result)
target.retention_exempt:
result = ServiceDeletionResult(
service_name=target.service_name,
status=ServiceDeletionStatus.SKIPPED,
records_deleted=,
records_retained=,
retention_reason=,
completed_at=datetime.now(timezone.utc),
error_message=
)
request.service_results.append(result)
target.legal_hold_check:
hold = ._check_legal_hold(subject_id, target.service_name)
hold:
result = ServiceDeletionResult(
service_name=target.service_name,
status=ServiceDeletionStatus.SKIPPED,
records_deleted=,
records_retained=,
retention_reason=,
completed_at=datetime.now(timezone.utc),
error_message=
)
request.service_results.append(result)
result = ._delete_from_service(subject_id, target)
request.service_results.append(result)
statuses = [r.status r request.service_results]
(s (ServiceDeletionStatus.COMPLETED, ServiceDeletionStatus.SKIPPED) s statuses):
request.status = DeletionStatus.COMPLETED
(s == ServiceDeletionStatus.FAILED s statuses):
request.status = DeletionStatus.PARTIALLY_COMPLETED
:
request.status = DeletionStatus.COMPLETED
.audit.log_deletion_complete(request)
request
() -> DeletionRequest:
result request.service_results:
result.status == ServiceDeletionStatus.COMPLETED:
remaining = ._check_data_exists(
request.subject_id, result.service_name
)
remaining > :
result.status = ServiceDeletionStatus.FAILED
result.error_message =
request.verified_at = datetime.now(timezone.utc)
request.verification_method =
all_verified = (
r.status (ServiceDeletionStatus.COMPLETED, ServiceDeletionStatus.SKIPPED)
r request.service_results
)
request.status = DeletionStatus.VERIFIED all_verified DeletionStatus.PARTIALLY_COMPLETED
.audit.log_deletion_verification(request)
request
() -> []:
() -> ServiceDeletionResult:
ServiceDeletionResult(
service_name=target.service_name,
status=ServiceDeletionStatus.COMPLETED,
records_deleted=,
records_retained=,
retention_reason=,
completed_at=datetime.now(timezone.utc),
error_message=
)
() -> :
4. Audit API
Audit Log Query Endpoints
paths:
/audit/events:
get:
operationId: queryAuditEvents
summary: Query privacy audit events
tags: [Audit]
security:
- OAuth2: [audit:read]
parameters:
- name: subjectId
in: query
schema:
type: string
- name: eventType
in: query
schema:
type: string
enum: [data_access, consent_change, deletion, dsar_submitted, dsar_completed, breach_detected]
- name: startDate
in: query
required: true
schema:
type: string
format: date-time
- name: endDate
[, , , ]
[, , ]
[]
[, , ]
API Security Patterns
Authentication and Authorization
| Endpoint Category | Auth Method | Scopes Required | Rate Limit |
|---|
| DSAR (data subject) | OAuth2 PKCE / JWT | dsar:read, dsar:write | 10 req/min |
| DSAR (admin) | OAuth2 Client Credentials | dsar:admin | 100 req/min |
| Consent (data subject) | OAuth2 PKCE / JWT | consent:read, consent:write | 30 req/min |
| Deletion (internal) | mTLS + API key | deletion:execute | 5 req/min |
| Audit (compliance) | OAuth2 Client Credentials | audit:read | 50 req/min |
Error Response Format
{
"error": {
"code": "PRIVACY_001",
"type": "identity_verification_required",
"message": "Identity verification is required before processing this request",
"details": {
"verificationMethods": ["email_verification", "document_upload"],
"supportUrl": "https://support.cipherengineeringlabs.com/privacy"
},
"requestId": "req_a1b2c3d4",
"timestamp": "2026-03-14T10:30:00.000Z"
}
}
References
- OpenAPI Specification 3.1.0
- GDPR Articles 12-22 (Data Subject Rights)
- CCPA/CPRA Sections 1798.100-1798.135
- RFC 6749 — OAuth 2.0 Authorization Framework
- RFC 7519 — JSON Web Token (JWT)
- OWASP API Security Top 10 (2023)
- Google Privacy Sandbox API Design Guidelines
- Apple App Tracking Transparency API Design Patterns
