openapi: 3.0.1

info:
  title: Ozone Connect - Consent HealthEvent & CheckAction APIs
  contact:
    name: Ozone Financial Technology Limited
  description: |
    This document provides the OAS3 specification for HealthAPIs that Checkare APIscalled forby Ozone Connect. to inform a financial institution Thesethat APIsa shouldconsent behas implementedbeen bycreated anor financialmodified.
institution
so that Ozone  These are also can ensure that the institution's Ozone Connect implementation is up and runningused to carry out actions to verify and augment a consent when it is being created.

    These APIs should be implemented by an financial institution.

    #### Document Structure
    The documentation contains a number of references of the form `XXX-999-999`. These are references
    to test case numbers in the Ozone Connect Test Harness that financial institutions may use to test their Ozone Connect implementations.

  version:  Version#### 2024.31Coming forsoon
CBUAE  servers:  The -following url: https://<your-ozone-connect-server>

tagschanges can be expected in the next release:
    - name: health-check
    description: |
      APIs that should be implemented by Financial Instituations to expose health check end-points

paths:
  /hello:
    get:
      operationId: hello
      summary: check connectivity without a mutual tls check
      tags:
        - health-check
      description:
        Check connectivity without a mutual tls CheckDetails.

        This health check is used to check that the end-to-end network connectivity is working as expected. This is a simple health check that does not require mutual TLS.
      responses:
        '200':
          description: OK
          content:
 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
    - query parameters for pagination will be introduced in alignment with CBUAE specifications
    - some additional query parameters for functional completeness will be introduced
    - the request and response object may be moved into `data` and `meta` objects for consistency

  version: Version 2024.31 for CBUAE

servers:
  - url: https://<your-ozone-connect-server>

tags:
  - name: consent-events
    description: |
      APIs that are called when a consent is created or modified.

  - name: consent-actions
    description: |
      APIs that are called to take actions on a consent

paths:

  /consent/event/{operation}:
    post:
      tags:
       - consent-events
      summary:  Called to inform a financial instituation that a consent has been created or modified
      description: |
        Used by financial institution to get a notification for updated consent.

      operationId: consentEvent
      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

        # Path param definitions
        - name: operation
          in: path
          description: specifies whether this is a POST or PATCH operation
          required: true
          schema:
            type: string
            enum:
              - post
              - patch

      requestBody:
        description: |
          Sends an event indicating the created or updated consent to an financial institution.
          This consists of the entire consent as stored in the consent Manager.

        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        "204":
          description: |
            Indicates the successful notification response.
            The response does not have a body

        "400":
          description: |
            Indicates that the financial institution could not process the event.

            Ozone will ignore these errors.
            The notification *will not* be retried.

            The change to the consent *will not* be rolled back.

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /consent/action/augment:
    post:
      tags:
        - consent-actions
      summary: Account action augumentation
      description: |
        The API is called by Ozone to allow a Financial Institution to augment additional information that may apply to the account consent

        The request body contains the entire consent record as stored in the Consent Manager.

      operationId: augmentAccountConsent

      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        "200":
          description: |
            Indicates a successful operation

            The response consists of fields that must be augmented into the consent.

            These fields will be different for each consent type.

            •••TODO••• Specify the fields that must be augmented for CBUAE consents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/augmentConsentResponse"
        "400":
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /consent/action/validate:
    post:
      tags:
        - consent-actions
      summary: Provides an opportunity for a financial institution to validate a consent before it is created
      description: |
        The API is called by Ozone to allow a financial institution to carry out additional validations before a consent is created.

        The request body contains the entire consent along with contextual information.

        Typically this could be used for situations like:
        - soft validation of the debtor account (e.g. to ensure that it is a debtor account managed by the financial institution)
        - populating charges and exchange rate information

        Note that a financial institution only need to implement this API where it needs to correlate information in the consent payload
        with data held in its systems. If this is not the case, "local" validations can be configured in Ozone that do not require a remote call.

        The financial institution must return a response that includes a status. If the status is set to `valid`, the consent is saved and processing continues.

        If the status is set to `invalid` the processing fails and an error response is sent to the TPP.

      operationId: validateConsent

      parameters:
        # common header parameters that set context
        - $ref: "#/components/parameters/providerId"
        - $ref: "#/components/parameters/aspspId"
        - $ref: "#/components/parameters/callerOrgId"
        - $ref: "#/components/parameters/callerClientId"
        - $ref: "#/components/parameters/callerSoftwareStatementId"
        - $ref: "#/components/parameters/apiUri"
        - $ref: "#/components/parameters/apiOperation"
        - $ref: "#/components/parameters/consentId"
        - $ref: "#/components/parameters/callerInteractionId"
        - $ref: "#/components/parameters/ozoneInteractionId"
        - $ref: "#/components/parameters/psuIdentifier"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/consent"

      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/consentValidateResponse"
        '400':
          description: failed operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


components:
  schemas:
    augmentConsentResponse:
      description: |
        Fields to be added to the consent

        ***TODO***: Specify the fields that must be augmented for CBUAE consents
      type: object
      additionalProperties: true

    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"

    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

    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

    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

    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 application/json:is initially created without a PSU identified.

       schema: The value must be specified once the consent is authorised.
      $ref: '#/components/schemas/HealthCheck200Response'properties:
   /hello-mtls:     getuserId:
      operationId    type: helloMtlsstring
      summaryrequired:
  check connectivity including mtls   - userId
  tags:    additionalProperties: true

  - health-check  ValidateResponseStatusEnum:
      descriptiontype: string
      enum:
Check connectivity including mutual TLS CheckDetails.   - valid
     This health check is- usedinvalid
to
check that the end-to-end network connectivity is working as expected including mutual tls. consentValidateResponse:
      type: object
      responsesproperties:
        '200'data:
          descriptiontype: OKobject
          contentproperties:
            application/jsonstatus:
              schema$ref: "#/components/schemas/ValidateResponseStatusEnum"
            code:
   $ref: '#/components/schemas/HealthCheck200Response'          '401'type: string
            description:
Returned when mtls connection could not be established              type: string

        meta:
 content:         $ref: "#/components/schemas/Meta"

 application/json:   Meta:
      type: object
   schema:   additionalProperties: false

    Error:
      $reftype: '#/components/schemas/HealthCheck4xxResponse'object
   /echo-cert:   properties:
 get:       operationIderrorCode:
echoCert       tags:   type: string
    - health-check     description: Error summary:code Providesidentifying informationthe aboutproblem theoccured
client cert that the server received   errorMessage:
   description:       type: string
This health check endpoint assists in debugging mutual tls client issues.description: Message describing what problem has occured
   The health check returns information aboutpropogateError:
the client certificate and the issuer of the client certificate thattype: theboolean
server received.         description: Whereoptional mtlsfield cannotif beerror established,want theto serverpropogate
will
return a 401parameters:
response.    aspspId:
  responses:    name: o3-aspsp-id
   '200':   in: header
      descriptionschema:
OK        type: string
 content:     required: true
      application/jsondeprecated: true
      description:
      schema:  Identifier for the financial institution that the request is targetted to.
     $ref: '#/components/schemas/HealthCheckCertResponse'  This header is deprecated and will be removed '401':in a future version of Ozone Connect. Use `o3-provider-id` instead.

description: Returned when mtls connectionproviderId:
could not be established   name: o3-provider-id
      contentin: header
      schema:
    application/json:    type: string
      required: true
   schema:   description: Identifier for the financial institution that the request is targetted to

 $ref: '#/components/schemas/HealthCheck4xxResponse'  componentscallerOrgId:

 schemas:     HealthCheck200Responsename: o3-caller-org-id
     type in: objectheader
      descriptionschema:
        Succesfultype: responsestring
on a health check   description: An identifier for properties:the organization calling the API

   connectionEstablished callerClientId:
      name: o3-caller-client-id
   type: boolean  in: header
      mtlsStatusschema:
 
        type: string
      description: An identifier  enum:
  for the OIDC clientId calling the API

    callerSoftwareStatementId:
   - established  name: o3-caller-software-statement-id
      in: header
 -  not-established   schema:
        type: -string
not-checked      description: An identifier for hostName:the software statement calling the API

    typeapiUri:
string        required:name: o3-api-uri
      in: header
- connectionEstablished     schema:
   - mtlsStatus    type: string
   - hostName  required: true
  HealthCheck4xxResponse:    description: The parameterised type:URL objectof the API being called by the description:caller

    apiOperation:
  Response when connection could not be establishedname: o3-api-operation
       propertiesin: header
       errorMessageschema:
 
        type: string

      required: true
       - errorMessage

    HealthCheckCertResponse:
      properties:
  description: The API operation carried out by the caller (e.g. GET, POST, PUT, DELETE, PATCH)

    connectionEstablishedconsentId:
      name: o3-consent-id
   type: boolean  in: header
      mtlsStatusschema:
          type: string
      description: The consentId  enum:
  for which this call is being made

    callerInteractionId:
   - established  name: o3-caller-interaction-id
      in: header
 - not-established    schema:
     hostName:   type: string
      typedescription: The stringinteraction ID passed in by the caller, if any

clientCertificate:    ozoneInteractionId:
      typename: objecto3-ozone-interaction-id
      in: header
  properties:    schema:
        subjecttype: string
      required: true
      typedescription: stringAn interaction ID generated by Ozone if the caller did not send in one. issuer:If the callerInteractionId is specified, this takes the same value.

    typepsuIdentifier:
string      name: o3-psu-identifier
   required:   in: header
      schema:
 - subject      type: string
     - issuerrequired: true
      requireddescription: A Base64 encoded representation of the psuIdentifier JSON -object.
connectionEstablished
  securitySchemes:
    bearerAuth:
- mtlsStatus     type: http
   - hostName  scheme: bearer
     - clientCertificatebearerFormat: JWT