Record an approved Consent visitor choice

Record a visitor choice

Use app_topolo_consent.consent.set to record one approved visitor choice for a configured purpose. This public integration route does not authenticate the visitor or grant administrative access.

POST /api/set-consent

Use the intended integration and the visitor’s legitimate choice. Resolve real identifiers from that integration; the examples below contain fictional values and were not executed. Preserve the actual Origin policy—do not spoof or remove a rejected Origin.

Request

Discover the current action and validate the reviewed input before an intended real write. Follow its current confirmation policy. A public Consent SDK key is an integration identifier, not an OAuth token, API key or workspace grant. A custom idempotencyKey is not supported by this action’s input schema.

Response

The route returns HTTP202 for both persistence outcomes:

The optional queue mirror, event insert and state upsert are separate steps, without a demonstrated cross-store transaction. Work can finish after the response or partially persist before failure. The response does not say whether an event insert was ignored or a state update won. Usage telemetry may be attempted separately; acceptance proves no metering, charge, notification or downstream enforcement outcome.

Worked examples

These complete responses are illustrative and unrun. Assume the fictional integration resolves, its Origin policy passes, analytics is configured, rate checking allows the request and source time is2026-10-20T08:00Z. No visitor preference, private record, queue or state was changed.

Fast persistence-promise completion

The persistence promise resolves within250ms. Verify current state separately.

Input:

{
  "projectKey": "fixture-project",
  "identityId": "identity_fixture_docs",
  "purposeId": "analytics",
  "decision": "denied",
  "source": "banner"
}

Response:

{
  "accepted": true,
  "projectKey": "fixture-project",
  "purposeId": "analytics",
  "decision": "denied",
  "syncStatus": "synced",
  "idempotencyKey": "fixture-project:identity_fixture_docs:analytics:denied:2026-10-20T08:00"
}

Uncertain persistence

The promise rejects or exceeds250ms; earlier queue/event effects may already exist. Reconcile before any further write.

Input:

{
  "projectKey": "fixture-project",
  "identityId": "identity_fixture_docs",
  "purposeId": "analytics",
  "decision": "denied",
  "source": "banner"
}

Response:

{
  "accepted": true,
  "projectKey": "fixture-project",
  "purposeId": "analytics",
  "decision": "denied",
  "syncStatus": "queued",
  "idempotencyKey": "fixture-project:identity_fixture_docs:analytics:denied:2026-10-20T08:00"
}

Purpose not configured

The key, surface and rate checks pass, but purpose_missing_fixture is absent from configuration. This input is schema-valid; the handler refuses it.

Input:

{
  "projectKey": "fixture-project",
  "identityId": "identity_fixture_docs",
  "purposeId": "purpose_missing_fixture",
  "decision": "denied",
  "source": "banner"
}

Response:

{
  "error": "invalid_consent_event"
}

Verify and handle uncertainty

1. Compare the actual returned integration, purpose and decision with the intended visitor operation. Preserve its time and request evidence.
2. Reconcile current subject state through supported, validated integration reads and its owner. Administrative logs require separate workspace authority, are bounded and do not by themselves prove the later state upsert succeeded. Preserve actual schema, permission and dependency refusals.
3. For queued or a lost response, reconcile possible queue/event/state effects before a separately approved repeat. A later invocation can produce a different minute key, event UUID and telemetry event. Do not automatically retry or run duplicates in parallel.
4. Verify effective data-use enforcement in the legitimate integration separately. A stored choice, GPC metadata, configured purpose or accepted response does not prove every tag, provider or model honored that policy.

A later approved preference change creates another event/state update. It does not delete the earlier record or undo downstream effects. Do not restore a guessed choice, erase audit history or invoke organization erasure as rollback.

Limits and refusals

The nominal write limit is120 per project/request-fingerprint/minute. Its optional KV counter is best-effort, non-atomic and fails open on missing/unreadable storage. It is not a global distributed rate guarantee. Missing or anonymous subject identifiers can be accepted but may not resolve through a later subject-state read.

A schema-invalid extra input field is a local action-validation failure, not a captured HTTP response. SDK/config cache or key mapping uncertainty needs the actual integration owner; do not guess another project or visitor.

Change log

• 2026-10-21: Added the public integration boundary, request/response fields, complete worked examples, persistence and retry limits, and separate verification of actual state versus effective policy. Examples are source-derived and unrun at immutable source4189f07126b1ecfc36aed6588f978346a7bafa2e; deployed serving/runtime association is not established here. Detailed normalization, partition, source and recovery semantics are retained in the paired agent layer.