HTTP API and errors

The SDK wraps these endpoints. You only need them directly if you are building your own client.

Endpoints

Endpoint	Auth	Purpose
GET /api/v1/consent?pk=	None	Consent presentation
POST /api/v1/attestations	Server credential	Mint an attestation (backend only)
POST /api/v1/consents?pk=	Attestation	Record an opt-in. Returns a contributor token and receipt
POST /api/v1/contributor-tokens?pk=	Attestation	Refresh the token for a consenting contributor
POST /api/v1/contributions?pk=	Contributor token	Submit a batch. Requires Idempotency-Key
POST /api/v1/consents/withdraw?pk=	Token or attestation	Withdraw
POST /api/v1/deletion-requests?pk=	Token or attestation	Request deletion
POST /api/v1/server/subjects/withdraw	Server credential	Withdraw on behalf of a user
POST /api/v1/server/subjects/deletion	Server credential	Delete on behalf of a user

Batches

POST /api/v1/contributions?pk=pk_live_…

Authorization: Bearer <contributor token>
Idempotency-Key: <batchId>

{
  "batchId": "b_8f2k1m9q",
  "sdkVersion": "0.1.0",
  "events": [ /* up to 50 events */ ]
}

Requests are limited to 64 KB. Rate limits apply per contributor and per environment.

Errors

error body

{ "error": { "code": "invalid_batch", "message": "…", "details": [{ "path": "events.0.payload.to", "message": "…" }] } }

Code	Meaning	SDK behaviour
token_expired, invalid_token	A new attestation is needed	Re-attests once and retries the same batch
token_revoked, consent_withdrawn	Withdrawn elsewhere	Moves to withdrawn and clears the queue
consent_renewal_required	The consent scope changed	Moves to renewal_required
collection_disabled, schema_not_approved, application_not_approved	Not permitted right now	Moves to unavailable
rate_limited (429), 5xx	Temporary	Backs off, honours Retry-After, bounded retries
invalid_batch, payload_too_large	A client bug	Drops the batch and calls onError