Consent manager

The Consent manager holds a shop's consent. It keeps the purposes the shop runs with the legal basis of each, the vendors and the cookies behind them, and the banner the visitor reads. A banner is never changed live: a draft is saved, previewed and then published as a numbered policy version. A version is frozen, carries a SHA-256 hash over its content, and is never edited or deleted. Every visitor decision is stored as one record that names the version the visitor was shown, and a record is never edited.

The app stores no IP address, no full user agent and no query string. A record keeps the browser family and major version when the storefront sends them, the path the decision was made on, and the consent id from the visitor's own cookie.

This page is for two readers:

• A storefront that shows the banner, reads the published policy and records decisions. Its calls are the delivery reads and POST /v1/consent-manager/records.
• The merchant-side integration that manages the registry and the banner, publishes versions and keeps the evidence for a data protection officer. Its calls are the rest.

To set up a shop, go in this order:

1. Set up the registry: POST /v1/consent-manager/defaults, then adopt vendors from the catalogue or declare them.
2. Edit the banner draft with PUT /v1/consent-manager/banner.
3. Preview the draft with POST /v1/consent-manager/policy/preview.
4. Publish it with POST /v1/consent-manager/policy/publish.
5. The storefront then reads the policy from delivery and records each decision.

Base path: https://api.revenexx.com/v1/consent-manager.

Each route needs its own scope, named after the route's capability, for example consent-manager.records.create, or consent-manager.* for every route of the app. See Scopes. A key without the scope is refused with 403.

The list routes take limit, offset and order (column, column.asc or column.desc). On the vendors list, limit defaults to 50 and is capped at 200.

Calls from the storefront

The storefront's calls go from its own server, the BFF, with an API key. They never come from the browser. See The BFF pattern for why, and Authentication for how the key is used.

The key needs consent-manager.delivery.policy to read the policy and consent-manager.records.create to store decisions. It also needs consent-manager.delivery.preview, but only if the storefront shows previews. Give the storefront key exactly these scopes, not consent-manager.*: the wildcard would also let it read and export every record, unlink contacts, prune and publish.

A visitor's decisions chain by consent_id, the random UUID v4 in the visitor's own rvx_consent cookie.

A record carries a contact only when the platform attaches a signed-in buyer's identity to the call. A call made with the storefront's API key alone leaves contact_id null, and unlinking a contact only matters for records that carry one.

Send the same X-Revenexx-Market header on POST /v1/consent-manager/records as on the delivery read. A record is stored under the market in the header, not the market of the version, so a record sent without it counts for the shop.

The market header

X-Revenexx-Market names the market a call is about. The banner draft, the policy versions and the records are kept per market. The shop is the tenant as a whole. It is what a call means when no market is named, which is an empty header value.

• Banner reads answer the market's own draft. A market without one gets the shop's draft with inherited: true.
• Banner writes save the draft of the market in the header, and an empty value saves the shop's draft. A market's first save starts from a copy of the shop's draft for the fields it does not send. A texts object replaces the stored one whole: languages and labels left out are dropped, so send the full set.
• Delivery answers the market's latest published policy, and the shop's when the market has none.
• Publish freezes the draft of the market named in the header. The market is never read from the body. The version number rises across all markets of the tenant. A version's material_number is the number of the latest material version of the same market, so it skips the numbers other markets used.

Registry

The registry holds the purposes, the vendors, the cookies and the catalogue of shipped vendors. It also answers the value sets the app owns.

A purpose has one legal basis: consent waits for the visitor's decision, legitimate_interest runs until the visitor objects, and necessary always runs. A purpose's code is fixed once it is created, because vendors, records and the visitor's cookie name it. A purpose that a vendor still serves cannot be deleted; switch it inactive instead, and it leaves the next published version.

A vendor names the purposes it serves. An active vendor with no active purpose blocks every publish and preview, not just itself, until it is linked to a purpose or switched inactive. A vendor's cookies are its storage entries (cookie, local storage, session storage, IndexedDB or pixel), each with a host of first-party or the third-party host.

The catalogue is a library of vendors met in B2B shops. Adopting an entry copies it into the tenant, and the copy is the tenant's: nothing re-reads the catalogue. When the shipped catalogue is newer, the adopted vendor is flagged with catalog_update and stays unchanged until the merchant refreshes it.

Refreshing an adopted vendor

Sending refresh: true on adopt takes the catalogue's current fields and replaces the vendor's cookies. It also overwrites the merchant's own edits to the vendor's catalogue fields and purpose links. code, is_active and position are kept. A vendor the merchant declared with the same code as the catalogue key counts as adopted: adopt refuses it with 409, and a refresh overwrites it. Without refresh, an adopted key is refused with 409.

Settings

The app has seven settings. Each one is set per market or per tenant. Five of them (consent_lifetime_days, banner_layout, show_cookie_details, banner_exempt_paths, google_consent_mode) are frozen into each version, so a change reaches visitors with the next publish. reconsent_on_publish applies at the moment you publish. proof_retention_days is read by every prune, so a change applies at the next prune run, the daily one included.

Banner and policy versions

The banner draft holds the layout and the labels per language, and the links to the shop's privacy policy and imprint. A visitor sees nothing from a draft until it is published.

• Layout is box, bar or modal, or null to follow the banner_layout setting.
• Labels are given per language. The labels title, body, accept_all, reject_all, save and settings are required before publishing.
• Reject all must be present in every language the draft speaks. Reject all always stands beside accept all, so the refusal applies wherever accept all is offered.

A publish or a preview is refused with 422 when:

Preview is refused by the same rules as a publish.

A publish renders the draft with the active purposes, the active vendors and the settings in every language the draft speaks. It stores the result as the next version, with a SHA-256 hash over the version's content field, serialized as compact JSON (no whitespace) with object keys sorted recursively and arrays in their stored order, as UTF-8. Recomputing the hash that way over a stored version's content and comparing it with the stored sha256 shows whether the content still matches what was published.

Versions are the evidence of what visitors read, so none can be edited or deleted: the version routes have no write method, and an edit or delete is answered with 405.

Material and renewal

material defaults to true, so a plain publish asks every visitor again. Send material: false for a change that should not: it keeps the visitors' earlier decisions valid. Two cases ask every visitor again anyway: the reconsent_on_publish setting is always, or there is no earlier version. The material_number of a version is the number of the latest material version of the same market, up to and including it. The storefront asks again when the number in a visitor's cookie is lower.

Delivery

Delivery is what a storefront reads.

Records

A record is one visitor decision. It is stored under the version that was shown, and it is never edited. A visitor's decisions chain by consent_id. A full withdrawal mints a new one. The consent_id is never handed to a tag.

POST /v1/consent-manager/records takes one decision, at most 4 KB. The required fields are consent_id, action, surface, policy_version_id and locale.

{
  "consent_id": "6f1c2a9e-4b7d-4e8a-9c3f-2d5b8e1a7f40",
  "action": "custom",
  "surface": "preferences",
  "policy_version_id": "0b9e4f7a-3c21-4d6e-8a5b-1f2e3d4c5b6a",
  "locale": "de",
  "decisions": { "purposes": { "statistics": "granted" }, "vendors": { "youtube": "granted" } },
  "user_agent_class": "Firefox 131",
  "client_ts": "2026-10-16T09:30:00Z",
  "page_path": "/produkte"
}

The ids in this example are placeholders: policy_version_id is the version.id the storefront got from delivery, and every purpose and vendor code must be in that version (here, youtube must have been adopted from the catalogue before the publish).

• action is one of accept_all, reject_all, custom, vendor_grant, withdraw or renew. vendor_grant is the visitor allowing one vendor. renew is a decision given again when the banner asks again. The labels are in GET /v1/consent-manager/vocabularies/record-actions.
• surface is one of first_layer, preferences, privacy_link or content_gate. The labels are in GET /v1/consent-manager/vocabularies/record-surfaces.
• decisions holds purposes and vendors by code, each granted, denied or objected. Every purpose of the shown version is stored explicitly. A necessary purpose is always stored granted. A consent purpose left out is stored denied; a legitimate_interest purpose left out is stored granted, and on reject_all or withdraw it is stored objected. An accept_all that denies or objects to a purpose, or a reject_all or withdraw that grants one, is refused with 422 and contradicts_action.
• user_agent_class is optional. It is the browser as family and major version. A longer value is reduced to that; a full user agent is never stored. Without it, the record keeps no browser class.
• client_ts is the visitor's clock when they decided, kept as a hint. A record retried on a later page view carries it.
• The contact is never read from the body. A record carries one only when the call is made for a signed-in buyer (see Calls from the storefront above).
• expires_at is the time received plus the version's consent lifetime. It is set by the app, not sent by the caller.

Records are never edited. An update answers 405. The only change a record ever sees is unlinking its contact, and the only removal is a prune past proof_retention_days.

Events

The app emits consent_record.created when a record is stored and policy_version.published when a version is frozen. See Events.