1 1. Introduction
2 2. Context
- 2.1 2.1. Lodge Intent
- 2.2 2.2. Retrieve Intent
- 2.3 2.3. Update Consent
3 3. Error Handling

1. Introduction

This page provides guidance on the Consent Manager API at the API Hub in the context of how the API can invoked at various stages during the consent lifecycle.

The information herein is intended to be informative, but the Consent Manager OpenAPI description remains the source-of-truth for Consent Manager Operations. This page must therefore be read in conjunction with the Consent Manager OpenAPI description page.

For information on the consent and payment state model and the statuses germane to the Consent Manager API please refer to the Open Finance standards.

2. Context

The Consent Manager is a consent management solution created by Ozone and part of the Open Finance Framework.

Consent Manager provides the following features:

Lodging of unauthorised consents (“intents”) sent by a TPP through a Pushed Authorisation Request.
State management throughout the consent lifecycle, including signalling of consent authorisation.
Enrichment of consent with, for example, TPP metadata or metadata provided by the LFI.
Payment state management.

The Consent Manager API can be called and at any time when the status of a consent or a payment changes. The most common use of the API is, however, during Authorisation Code flow.

The activity diagram to the right shows a high-level view of these operations.

The following sections provide excerpts of the API Hub Sequence Diagrams that describe the end-to-end flow and show the high-level operations in context to provide clarity on how the Consent Manager API is used.

High-Level Consent Operations - Authorisation Code Flow

2.1. Lodge Intent

An intent is lodged is invoked as a result of a Pushed Authorisation Request and results in a Consent resource being created.

When an intent is authorised by the User it is then termed a consent.

Operation URL and method	`post /consents`
Initiated When	A TPP submits a Pushed Authorisation Request
Invoked By	API Hub
Data Enrichment	TPP Metadata
Other Use Cases	No other uses cases are currently supported

Consent Lodging Flow

2.2. Retrieve Intent

An LFI retrieves a given consent during Authorisation Code flow.

Retrieving consent allows the LFI to render an authorisation screen to enable the User to confirm the details of consent.

Operation URL and method	`get /consents/{consentId}`
Initiated When	An LFI needs to retrieve the consent ready to authenticate the User and for the User to authorise consent
Invoked By	LFI
Data Enrichment	None
Other Use Cases	Consent synchronisation (LFI retrieves current state of consent)

2.3. Update Consent

An LFI updates a given consent after the User has complete the authentication and authorisation journey.

The LFI must update the consent regardless of whether the consent is authorised or rejected.

Operation URL and method	`patch /consents/{consentId}`
Initiated When	An LFI needs to update the consent with properties of the authenticated party, such as User identifiers, status, or multi-authorisation requirements.
Invoked By	LFI
Data Enrichment	As described above and outlined in the OpenAPI description
Other Use Cases	Updating User identifiers for multi-authorisation accounts (for example, corporate accounts with multiple approvers).

3. Error Handling

The Consent Manager API is REST API and implements these semantics, namely:

Failures scenarios will be signalled by a HTTP status code outside the 200 range.
An appropriate errorCode and errorMessage value will be returned.

The table below shows the possible 400 errors that can be returned. Please note that variables are provided in the message to indicate where the error message text will vary.

	Error Code	Error Message	Description

	Error Code	Error Message	Description
1	general_error	default: An error occurred with an indeterminate error code {variable}	Unexpected validation error encountered when processing consent.
2	expected_modification	expected_modification: Could not patch consent	Could not patch consent as no modification to the consent attributes sent.
3	invalid_message_format	invalid_message_format: json payload does not match schema ${JSON as string(variable)}	Consent payload does not match expected schema.
4	invalid_page_number	invalid_page_number: ensure {variable.query} query parameter is valid number and greater than zero	Could not retrieve consents as requested page number is not numeric.
5	invalid_page_size	invalid_page_size: ensure {variable.query} query parameter is valid number and greater than zero	Could not retrieve consents as requested page size is not numeric.
6	consent_status_invalid_patch_request	consent_status_invalid_patch_request: Consent status must be one of [{variable.allowedConsentStatuses}]	Invalid consent status submitted in request payload.
7	consent_status_invalid	consent_status_invalid: A consent can not be patched if it is already in terminal state	Consent is already in a state that cannot be modified as the previous state is terminal.
8	consent_body_missing_revocation	consent_body_missing_revocation: The consent cannot be revoked without revocation data	Revocation data must be supplied to revoke a consent.
9	ensure_consent_deleted	ensure_consent_deleted: failed to delete consent	Consent delete failed due to an unknown error.
10	invalid_consentId	invalid_consentId: Ensure ConsentId is valid	Consent identified by requested consent identifier not found.
11	consent_type_invalid	consent_type_invalid: consent type {variable.consentType} is not valid	The consent type value is not valid
12	consent_type_not_supported	consent_type_not_supported: consent type {variable.consentType} is not valid	The consent type value is not supported
13	invalid_date_format	invalid_date_format: ensure paymentResponse.statusUpdateDateTime is in ISO 8601 format	Invalid date format submitted in Payment Log operation.
14	date_undefined	date_undefined: paymentResponse.statusUpdateDateTime is required	Invalid date format submitted in Payment Log operation.
15	incorrect_payment_patch_status	incorrect_payment_patch_status: valid status is needed	Invalid status submitted in Payment Log operation.
16	payment_not_found	payment_not_found: payment data not found	Payment data not found in Payment Log operation.
17	status_undefined	status_undefined: paymentResponse.status is required	Payment status not provided in Payment Log operation.
18	payment_id_not_found	payment_id_not_found: paymentId not found in params	Payment ID not found in Payment Log operation.
19	payment_type_not_found	payment_type_not_found: payment type not found	Payment type not found in Payment Log operation.
20	failed_to_patch_request	failed_to_patch_request: failed to patch request	Generic patch failure
21	not_a_number	not_a_number: not a number	Generic non-numeric validation failure
22	consent_type_not_found	consent_type_not_found: consent type not found	Consent type not found
23	authorization_time_expired	authorization_time_expired: time to authorize the consent status expired {variable.lhs} === {variable.rhs}	Consent authorisation window has passed and therefore cannot be processed.
24	mandatory_field_not_defined.	mandatory_field_not_defined : instruction {variable.msg} for object {variable.no} not found.	Generic error for missing mandatory properties
25	payment_status_invalid_patch_request	payment_status_invalid_patch_request: Consent status must be one of [{variable.allowedConsentStatuses}]	Invalid payment status submitted in request payload for Payment Log.

Please refer to the OpenAPI description for more details on the structure of the error response payload.

API Hub Documentation v6

Consent Manager API Guide