API and event contracts

The REST API is specified in public/schemas/openapi.yaml. The checked-in contract is authoritative; generated SDKs and docs must not introduce fields.

Resource surface

Endpoint	Core operations
/v1/notices	list/create versions, review, publish
/v1/purposes	create/version/approve/retire
/v1/consents	request/record/search receipt
/v1/consents/{id}/withdraw	append withdrawal and orchestrate
/v1/data-principals/{ref}/preferences	read/update scoped preferences
/v1/rights-requests	intake, task, decision, delivery
/v1/grievances	intake, message, resolve/escalate
/v1/retention-policies	version rules
/v1/legal-holds	propose/approve/review/release
/v1/deletion-jobs	plan/approve/execute/verify
/v1/incidents	intake/assess/clock/notify/close
/v1/vendors	vendor/processor/contract/subprocessor
/v1/processing-activities	inventory and flows
/v1/evidence	collect/test/export
/v1/connectors	register/test/health/revoke

Authentication and authorization

Human console uses customer OIDC/SAML via Authorization Code + PKCE. APIs use OAuth 2.0 client credentials with audience and granular scopes; high-trust connectors use mTLS plus short-lived tokens. No long-lived bearer token appears in config or audit.

Example scopes: consents:write, rights:triage, incidents:manage, connectors:instructions:poll, evidence:export. The API evaluates tenant/entity/resource context in addition to scope.

Request semantics

• POST commands require Idempotency-Key; retain key/result digest for at least the operation’s safe replay window.
• Updates require If-Match resource version; conflicts return 409 with no silent last-write-wins.
• Cursor pagination is stable and tenant-scoped; max page size 200 by default.
• Rate limits are per tenant, client, endpoint and abuse signal; 429 includes Retry-After.
• Correlation ID is accepted or generated and returned; no personal data is encoded in it.
• Date-time uses RFC 3339 with offset; persisted deadlines are UTC plus IANA time zone/source.

Consent example

POST /v1/consents HTTP/1.1
Authorization: Bearer …
Idempotency-Key: syn-98e350
X-Correlation-ID: cor-synthetic-01
Content-Type: application/json

{
  "principal_ref": "subj_H7K4Q2",
  "purpose_version_id": "pur_demo_v3",
  "notice_version_id": "not_demo_v5",
  "action": "grant",
  "channel": "mobile_app",
  "occurred_at": "2026-07-29T09:31:22+05:30",
  "proof": { "method": "authenticated_session", "reference": "proof_synthetic" }
}

Response 201 carries receipt ID, hash, recorded time and resource version. Repeating the same key and body returns the same result; changing the body returns 409 IDEMPOTENCY_KEY_REUSED.

Event envelope

{
  "specversion": "1.0",
  "id": "evt_synthetic_01",
  "source": "urn:opendpdp:tenant:synthetic",
  "type": "in.opendpdp.consent.withdrawn.v1",
  "subject": "consent/cr_synthetic_01",
  "time": "2026-07-29T09:41:00Z",
  "datacontenttype": "application/json",
  "tenant_ref": "tnt_synthetic",
  "correlation_id": "cor_synthetic_01",
  "causation_id": "cmd_synthetic_02",
  "data": { "purpose_version_id": "pur_demo_v3", "principal_ref": "subj_H7K4Q2" }
}

Webhook signature: v1=HMAC-SHA-256(secret, timestamp + "." + raw_body). Accept within a configured skew (default five minutes), reject reused delivery ID, rotate overlapping secrets, return 2xx after durable acceptance. Retry exponential backoff with jitter for 24 hours by default, then dead letter and alert. Ordering is per aggregate sequence, not global.

SDK priority

1. TypeScript/JavaScript for web/service integration;
2. Java for bank/insurer enterprise stacks;
3. Python for automation/data operations;
4. Go for agents and platform services.

MVP ships TypeScript types/client and Java examples, not four supported SDKs. Mobile SDK guidance uses platform secure storage, app-attested channel metadata only where justified, offline idempotency and no advertising identifier.

Versioning

Backward-compatible fields are additive within /v1; consumers ignore unknown fields. Semantic event types carry schema major. Breaking REST changes use a new media/API version with migration and deprecation window. Historic receipts/events retain their original schema and canonical bytes.