...
| Awesome api app render macro | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
openapi: 3.0.1
servers:
- url: https://{your-cm-serverx}
description: Consent manager for the tenant
info:
title: Consent Manager Apis
description: |
This document provides the OAS3 specification for the APIs provided by the Ozone Consent Manager.
These APIs are implemented by Ozone and should be called by the financial institution to find, modify and delete consents.
#### Coming soon
The following changes can be expected in the next release:
- some enumeration and object definitions remain to be aligned with CBUAE specifications. These will be updated
- specific changes expected in the next release have been marked as ***TODO*** in the document
contact:
name: Ozone Financial Technology Limited
version: Version 2024.31
tags:
- name: consents
- name: consent-groups
- name: consents-by-psu
- name: consents-by-account
- name: payments
- name: actions
paths:
/consents:
post:
tags:
- consents
summary: Creates a new consent
description: |
Used by Ozone to create a new consent using a Heimdall interaction.
operationId: addConsent
requestBody:
description: |
Creates a new consent in the consent Manager.
The API is primararily used by Ozone for creating consents when requested by a TPPs.
Financial Institutions may use this end-point to import consents and for supporting externally managed consents. This is not part of the CBUAE standard.
required: true
content:
application/json:
schema:
type: object
description: |
The request body for creating a new consent.
The body consists of the RAR request that is sent by the TPP to the authorization server.
***TODO*** Import the schemas for the RAR requests from the CBUAE specification
additionalProperties: true
responses:
'201':
description: |
Indicates the successful creation of a consent
content:
application/json:
schema:
$ref: "#/components/schemas/ConsentPostResponse"
'400':
description: |
Indicates a failure to create the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
get:
tags:
- consents
summary: Retrieves all the consents that meet the search criteria
description: |
Retrieves an array of consents that meets the search criteria.
If no consents could be found, then an empty array is returned.
This API may be used by an financial institution to get a "stream" of consents that have been created or updated since a given timestamp.
operationId: getAllConsents
parameters:
- name: updatedAt
in: query
schema:
type: number
required: false
description: |
Select only consents updated after the specified time
- $ref: "#/components/parameters/consentType"
- $ref: "#/components/parameters/status"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/pageSize"
responses:
'200':
description: |
Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/multiConsentResponse"
'400':
description: Indicates a failure to retrieve the consents
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/consents/{consentId}:
get:
tags:
- consents
summary: Retrieve a consent by its id
description: Retrieves a consent by its id.
operationId: getConsentsByConsentId
parameters:
- $ref: "#/components/parameters/consentId"
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
$ref: "#/components/schemas/consent"
meta:
$ref: "#/components/schemas/meta"
'400':
description: |
Indicates a failure to retrieve the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
patch:
tags:
- consents
summary: Patches one or more fields in a consent
description: |
This operation allows an financial institution modify fields within a consent's `consentBody`.
Typically, this API would be called after the PSU has authorised a consent. This would
allow the financial institution to "patch in" the `psuIdentifier` and `accountIds` associated with the
consent.
This is also called as authentication progresses for a multi-auth consent.
operationId: patchConsent
parameters:
- $ref: "#/components/parameters/consentId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/cbuaePatchBody"
responses:
'204':
description: |
Indicates a successful operation.
The response does not have a body.
'400':
description: |
Indicates a failure to patch the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/consents/{consentId}/audit:
get:
tags:
- consents
summary: Retrieve an audit of a consent by the consent's id
description:
Retrieves an audit of a consent by the consent's id.
The audit log is a low-level record of all changes applied to a Consent
throughout its life-cycle
operationId: getAuditConsentsByConsentId
parameters:
- $ref: "#/components/parameters/consentId"
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
type: object
required:
- providerId
- operation
- timestamp
- fkMongoId
- fkId
- id
- ozoneInteractionId
properties:
providerId:
type: string
description: |
The provider id of the financial institution that made the change
operation:
type: string
description: |
Like "create" or "patch"
timestamp:
type: integer
fkMongoId:
type: string
description: |
A unique identifier for the audit log in mongodb
fkId:
type: string
description: |
A unique identifier for the consentId
id:
type: string
description: |
A unique identifier for the audit log
ozoneInteractionId:
type: string
description: |
The ozone interaction id assigned to the interaction that caused this changed. Useful for looking up the api-log.
Note - this is not the "heimdall Interaction Id" - this is an identifier for the API log
callerDetails:
type: object
description: |
The details of the API caller that made the change
additionalProperties: false
properties:
callerOrgId:
type: string
callerClientId:
type: string
callerSoftwareStatementId:
type: string
patchFilter:
type: string
description: |
Low-level operation description of the selector for the patch
patch:
type: string
description: |
Low-level operation description of the patch that was applied at the storage level
meta:
$ref: "#/components/schemas/meta"
'400':
description: |
Indicates a failure to retrieve the consent's audit trail
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/consent-groups/{consentGroupId}/consents:
get:
tags:
- consent-groups
summary: Retrieves consents within a consent group
description: |
Retrieves an array of consents that are within a consent group.
If no consents could be found, then an empty array is returned.
For CBUAE, a consent group id is the `BaseConsentId`
operationId: getConsentsInConsentGroup
parameters:
- name: consentGroupId
in: path
schema:
type: string
required: true
description: |
Select consents within the consentGroupId
- $ref: "#/components/parameters/consentType"
- $ref: "#/components/parameters/status"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/pageSize"
responses:
'200':
description: |
Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/multiConsentResponse"
'400':
description: Indicates a failure to retrieve the consents
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/psu/{userId}/consents:
get:
tags:
- consents-by-psu
summary: Retrieves all the consents associated with a given PSU
description: |
Retrieves an array of consents associated with the PSU.
If no consents could be found associated with the PSU, then an empty array is returned.
The userId path parameter is matched with the `psuIdentifiers.userId` field in the consent.
operationId: getConsents
parameters:
- $ref: "#/components/parameters/userId"
- $ref: "#/components/parameters/consentType"
- $ref: "#/components/parameters/status"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/pageSize"
responses:
'200':
description: |
Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/multiConsentResponse"
'400':
description: Indicates a failure to retrieve the consents
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/accounts/{accountId}/consents:
get:
tags:
- consents-by-account
summary: Retrieve consents of a account by its id
description: |
Retrieve consents of a account by its id
operationId: getAccountIdConsents
parameters:
- name: accountId
in: path
schema:
type: string
required: true
description: Identifier for the account
- $ref: "#/components/parameters/consentType"
- $ref: "#/components/parameters/status"
- $ref: "#/components/parameters/page"
- $ref: "#/components/parameters/pageSize"
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/multiConsentResponse"
'400':
description: |
Indicates a failure to create the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/consent-groups/{consentGroupId}/consents/action/revoke:
post:
tags:
- actions
summary: Revokes consents within a consent group
description: |
Revokes consents that are within a consent group.
operationId: revokeConsentsInConsentGroup
parameters:
- name: consentGroupId
in: path
schema:
type: string
required: true
description: |
Select consents within the consentGroupId
requestBody:
description: |
An end-point for revoking a consent within a consent group.
This is similar in behaviour to the consent revocation endpoint, but operates on a consent group id parameter instead
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RevokeConsent"
responses:
'204':
description: |
Indicates a successful operation.
The response does not have a body.
'400':
description: Indicates a failure to revoke the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/consents/{consentId}/action/revoke:
post:
tags:
- actions
summary: Revoke a consent by its id
description:
Revokes a consent by its id along with any associated access and refresh tokens.
This API is used by ozone internally to revoke consents.
The API should be used by a financial institution to revoke consents (rather than simply patching the consent) to also revoke the tokens associated with the consent
operationId: revokeConsentsByConsentId
parameters:
- $ref: "#/components/parameters/consentId"
requestBody:
description: |
An end-point for revoking a consent.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/RevokeConsent"
responses:
'204':
description: |
Indicates a successful operation.
The response does not have a body.
'400':
description: |
Indicates a failure to revoke the consent
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/payment-log:
get:
tags:
- payments
summary: Retrieve a payment log by its consent id or account id
operationId: getAuditConsentsByConsentIdw
description: |
Either one of the query parameters can be used, not both.
parameters:
- name: consentId
in: query
schema:
type: string
required: true
description: |
Identifier for the consent
- name: accountId
in: query
schema:
type: string
required: true
description: |
Identifier for the account
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
type: object
required:
- consentId
- paymentType
- paymentId
- idempotencyKey
- paymentResponse
- tpp
- accountId
- psuIdentifiers
- interactionId
- authorizationCode
- requestBody
- requestHeaders
properties:
consentId:
type: string
description: |
A ConsentId generated by the financial institution for the consent.
paymentType:
type: string
description: |
The underlying payment type
•••TODO••• Specify the payment types supported for CBUAE
paymentId:
type: string
idempotencyKey:
type: string
paymentResponse:
type: object
description: |
The payment response as received from the financial institution as a result of a `make-payment` call
properties:
id:
type: string
description: |
A unique id for the payment in uuid-v4 format.
status:
type: string
description: |
The current status of the payment
•••TODO••• Specify the payment types supported for CBUAE
creationDateTime:
type: string
pattern: ($date-time)
description: |
An ISO date-time representing when the consent was created
statusUpdateDateTime:
type: string
pattern: ($date-time)
description: |
An ISO date-time representing when the consent status was last updated
signedResponse:
type: string
tpp:
$ref: "#/components/schemas/tpp"
accountId:
type: integer
psuIdentifiers:
$ref: "#/components/schemas/psuIdentifiers"
interactionId:
$ref: "#/components/schemas/apiLogInteractionId"
authorizationCode:
type: object
properties:
paymentId:
type: string
accessTokenHash:
type: string
currentDateTime:
type: string
pattern: ($date-time)
requestBody:
type: object
description: |
The payment request body as received from the TPP
•••TODO••• Import in the schema as supported for CBUAE
additionalProperties: true
signedRequestBody:
type: string
requestHeaders:
type: object
description: |
The entire set of Http request headers that was received by Ozone from the TPP
additionalProperties: true
meta:
$ref: "#/components/schemas/meta"
'400':
description: |
Indicates a failure to retrieve the payments
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/payment-log/{id}:
patch:
tags:
- payments
summary: Patches one or more fields in a payment-log based on id .
description: |
This operation allows an modify fields within a payment's `paymentResponse`.
This is used by the financial institutions to update the status of a payment
operationId: patchPymentlog
parameters:
- $ref: "#/components/parameters/id"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CbuaePatchPaymentRecordBody"
responses:
'204':
description: |
Indicates a successful operation.
The response does not have a body.
'400':
description: |
Indicates a failure to retrieve the payments
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
components:
schemas:
errorResponse:
type: object
properties:
errorCode:
type: string
description: Error code identifying the problem occured
errorMessage:
type: string
description: Message describing what problem has occured
meta:
type: object
additionalProperties: false
apiLogInteractionId:
type: object
properties:
ozoneInteractionId:
type: string
clientInteractionId:
type: string
additionalProperties: false
required:
- ozoneInteractionId
tpp:
type: object
description: |
The TPP record as held by Ozone.
If Ozone TPP Connect has been integrated into a directory, the `directoryRecord` provides the TPP's directory record as held by Ozone in base 64 encoded format.
required:
- clientId
- orgId
- softwareStatementId
- tppName
properties:
clientId:
type: string
description: The clientId for the TPP as issued by Ozone
orgId:
type: string
description: The organization id for the TPP
softwareStatementId:
type: string
description: The organization id for the TPP
tppName:
type: string
description: The name of the TPP
directoryRecord:
type: string
description: The latest copy of the TPP directory record if the TPP has registered with a directory
additionalProperties: false
psuIdentifiers:
type: object
description: |
The PSU that is associated with this consent.
The `PSUIdentifiers` object may have artitrary custom fields that an financial institution may use to
identify the PSU.
However, all `PSUIdentifiers` must have a mandatory `userId` field that provides a unique
user id for the PSU.
The consent is initially created without a PSU identified.
The value must be specified once the consent is authorised.
properties:
userId:
type: string
required:
- userId
additionalProperties: true
newConsent:
type: object
properties:
id:
type: string
description: |
A unique identifier for the consent in uuid-v4 format.
consentGroupId:
type: string
description: |
A unique identifier for the consent group in uuid-v4 format.
The consent group id is used to group together consents that are related to each other.
requestUrl:
type: string
format: url
description: |
The request url of Http request that was received by Ozone from the TPP
consentType:
type: string
description: |
The type of the consent that is being created.
Each financial institution's instance may support a different set of consent types
The Consent Manager supports the creation of consents of different consent types depending on the standards supported.
•••TODO••• Specify the consent types supported for CBUAE
status:
type: string
description: |
The current status of the consent
The Consent Manager ensures that this field is synchronised with the status of the consent body (the disposition of that field depending on the underlying standard)
•••TODO••• Specify the consent statuses supported for CBUAE
request:
type: object
description: |
The entire Http request body that was received by Ozone from the TPP to create the consent.
The Consent Manager uses the consent type to identify the schema
that should be used to validate the request. (These schemas are defined by the
underlying standard)
additionalProperties: true
requestHeaders:
type: object
description: |
The entire set of Http request headers that was received by Ozone from the TPP
additionalProperties: true
consentBody:
$ref: "#/components/schemas/cbuaeConsentBody"
interactionId:
type: string
description: |
The heimdall interaction id that this consent is associated with.
tpp:
$ref: "#/components/schemas/tpp"
ozoneSupplementaryInformation:
type: object
additionalProperties: true
updatedAt:
type: number
required:
- id
- consentType
- request
- requestHeaders
- tpp
additionalProperties: true
patchedConsent:
type: object
properties:
psuIdentifiers:
$ref: "#/components/schemas/psuIdentifiers"
accountIds:
type: array
items:
type: string
minItems: 1
description: |-
An array of account ids associated with the consent. The array must be populated once consent has been authorised.
For payment consents, the array must always have one element - the debtor account from which the payment will be made
For CBPII consents, the array must always have one element - the account for which CoF requests will be answered
For AIS requests, the array may contain multiple values, representing each of the payment accounts for which an AIS service will be provided.
supplementaryInformation:
description:
Contains additional information at the discretion of the financial institution.
type: object
additionalProperties: true
interactionId:
type: string
description: The heimdall interaction id that this consent is associated with. This is updated by heimdall and must not be set by financial institutions.
paymentContext:
type: object
additionalProperties: true
ConnectToken:
type: string
description: A bearer token that will be sent as the `Authorization` header for calls to Ozone Connect made under this consent.
additionalProperties: true
CbuaePatchPaymentRecordBody:
type: object
description: |
Describes the fields to be patched and their corresponding values.
•••TODO••• Specify the exact fields that are may be patched into the request based on CBUAE standard
required:
- paymentResponse.status
additionalProperties: false
properties:
paymentResponse.status:
type: string
description: |
The current status of the payment
•••TODO••• Specify the payment statuses supported for CBUAE
cbuaeConsentBody:
type: object
description: |
An object representing the current state of the consent.
This includes the entire request, augmented by additional computed properties
(e.g. ids, charges etc)
The Ozone Consent Manager caters to consents from various standards. The actual schema for each consentBody would be determined by the underlying standard.
•••TODO••• Import the schemas for the consentBody from the CBUAE specification
additionalProperties: true
cbuaePatchBody:
description: |
Describes the fields to be patched and their corresponding values.
***TODO*** Specify the exact fields that are may be patched into the request
type: object
additionalProperties: false
properties:
psuIdentifiers:
$ref: "#/components/schemas/psuIdentifiers"
accountIds:
type: array
items:
type: string
minItems: 1
description: |-
An array of account ids associated with the consent. The array must be populated once consent has been authorised.
For service initiation, the array must always have one element - the debtor account from which the payment will be made
For data sharing requests, the array may contain multiple values, representing each of the payment accounts for which an AIS service will be provided.
supplementaryInformation:
description:
Contains additional information at the discretion of the financial institution.
type: object
additionalProperties: true
status:
description: |
The current status of the consent for the consent.
•••TODO••• Specify the consent statuses supported for CBUAE
type: string
consentBody.Meta.MultipleAuthorizers:
$ref: "#/components/schemas/AEMetaMultiAuthorization"
AEMetaMultiAuthorization:
type: "object"
description: |
Meta Data with Multi-Authorization relevant to the payload.
For a payment, it represents any Authorizers within the financial institution domain that are involved in approving the payment request.
properties:
TotalRequired:
description: |
The total number of Authorizers required to process the request
type: "number"
Authorizations:
type: "array"
items:
description: |
Authorizer
type: "object"
properties:
AuthorizerId:
description: |
The Authorizer's Identifier
type: "string"
AuthorizerType:
description: |
The Type of Authorizer. For example, Financial, Management, etc.
type: "string"
AuthorizationDate:
description: |
The DateTime of when the Authorization occurred. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2023-04-05T10:43:07+00:00
type: "string"
format: "date-time"
AuthorizationStatus:
description: |
The Status reflecting the Authorizer's final decision regarding the request
type: "string"
enum:
- "Pending"
- "Approved"
- "Rejected"
additionalProperties: false
additionalProperties: false
additionalProperties: false
consent:
description: |
A consent in its current state.
If the consent has been authorised, then it can be expected that the financial institution would have patched in `accountIds` and `psuIdentifier` fields.
Additionally, the financial institution may also patch in an arbitrary set of fields along with consent in the `supplementaryInformation` field.
•••TODO••• Import the schemas for the consent from the CBUAE specification
allOf:
- $ref: "#/components/schemas/newConsent"
- $ref: "#/components/schemas/patchedConsent"
multiConsentResponse:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: "#/components/schemas/consent"
meta:
$ref: "#/components/schemas/meta"
ConsentPostResponse:
type: object
required:
- data
- meta
properties:
data:
$ref: "#/components/schemas/newConsent"
meta:
$ref: "#/components/schemas/meta"
RevokeConsent:
type: object
required:
- revokedBy
properties:
revokedBy:
type: string
enum:
- ADR
- CONSUMER
- COLLEAGUE
- REGISTER
- EXPIRATION
- AMENDMENT
revokedByPsu:
type: object
properties:
userId:
type: string
parameters:
consentId:
name: consentId
in: path
schema:
type: string
required: true
description: |
Identifies the consent by an id
id:
name: id
in: path
schema:
type: string
required: true
description: |
Identifies the payment by an id
userId:
name: userId
in: path
schema:
type: string
required: true
description: |
Identifies the PSU associated with a consent.
This should match up with the `psuIdentifier.userId` field.
page:
name: page
in: query
schema:
type: string
format: int32
minimum: 1
required: false
description: |
The page number to retrieve in a paginated response
pageSize:
name: pageSize
in: query
schema:
type: string
format: int32
minimum: 1
required: false
description: |
The maximum rows to retrieve in a given page. Defaults to 25 if not specified.
consentType:
name: consentType
in: query
schema:
type: string
description: Consents of particular accountId
required: false
status:
name: status
in: query
schema:
type: string
description: Status of the consent
required: false
securitySchemes:
api_key:
type: apiKey
name: api_key
in: header
description: TLS-MA and Jws in authorization header
|
...