This is v2.2-draft — a working draft of the v2.2 standards, published for review and not yet ratified. It MUST NOT be used as the basis for a production implementation. For the current standards, switch to v2.1 using the version selector. See the v2.1 → v2.2-draft changelog for every change in this version.
Consent Events & Actions — API Guide 3 min read
This guide covers the implementation of the Consent Events & Actions endpoints on your Ozone Connect server. These are endpoints your LFI exposes and the API Hub calls.
What must already be in place
Before implementing these endpoints, ensure the following are in place:
- API Hub onboarded — Your API Hub instance is provisioned and your environment-specific configuration is complete
- Ozone Connect base URL configured — The API Hub knows the base URL of your Ozone Connect server. See Ozone Connect Base URL
- Connectivity verified — Bidirectional mTLS connectivity confirmed between your systems and the API Hub. See Connectivity & Certificates
POST /consent/action/validate
API Sequence Flow
The API Hub calls this endpoint during consent creation, before the consent is stored. The trigger is a TPP submitting a POST/par request to the API Hub.
What to validate
Your LFI SHOULD validate that the consent is one you can support. At a high level, typical checks include:
- Does the consent version match what your LFI supports?
- Are the requested permissions within the scope of what your LFI offers?
Each consent type defines its own specific validation rules in its Requirements page (e.g. Bank Data Sharing — Requirements). Refer to the Requirements page for each consent type your LFI supports to understand the full set of validation checks you MUST implement.
Response schema
| Field | Type | Required | Description |
|---|---|---|---|
data.status | string | Yes | valid or invalid |
data.code | string | No | An error code — returned when status is invalid |
data.description | string | No | A human-readable description of why the consent was rejected |
meta | object | Yes | Empty object {} |
See the POST/consent/action/validate API Reference for the full request and response schemas.
POST /consent/event/{operation}
API Sequence Flow
The API Hub calls this endpoint to notify your LFI of consent lifecycle changes:
| Operation | Trigger |
|---|---|
POST/consent/event/post | A consent has been created — i.e. after POST/par succeeds (and after validation, if configured) |
POST/consent/event/patch | A consent has been updated — e.g. status changed to Authorized, Rejected, Revoked, or Expired |
What to do with the event
If your LFI stores consents locally, use these events to keep your local state in sync with the API Hub:
- On
post— Store the new consent in your local system - On
patch— Update your local consent record to reflect the latest state
The request body contains the full consent object as stored in the API Hub's Consent Manager — not a diff. Your LFI can replace its local record entirely with the received payload.
The API Hub is the single source of truth for consent state. Your local copy is a convenience cache. If there is ever a discrepancy, the Hub's state takes precedence.
Response
Your LFI MUST return 204 No Content to acknowledge receipt.
If your endpoint returns an error (e.g. 400 or 500), the API Hub will not retry the notification and will not roll back the consent change. The consent state in the Hub proceeds regardless.
Because the Hub is the source of truth and your local copy is a cache, any missed event can be reconciled by reading from the Consent Manager:
- Handler received the payload but failed to process it — you have the
consentId, so call GET/consents/{consentId}to fetch the latest state. - Your system was offline and never received the event — reconcile lazily at end user login by calling GET
/psu/{userId}/consentsbefore rendering the CMI.
LFIs that do not maintain a local consent cache do not need to reconcile — read from the Consent Manager on demand.
Full request and response schemas
- POST
/consent/action/validate— Full request and response schema - POST
/consent/event/{operation}— Full request and response schema