1. Introduction

1.1 Purpose

The AlTareq Centralised Authentication and Authorization (CAAP) solution provides Licensed Financial Institutions (LFIs) with the means to outsource authentication of the User and authorization of consent to the API Hub through the AlTareq mobile application.

This document describes the technical steps required for Third‑Party Providers (TPPs) and LFIs to integrate with the AlTareq mobile application. It covers mandatory API descriptions, deep‑link conventions, and security controls needed to enable end users to authorise and manage open‑banking consents securely from their mobile device.

1.2 Glossary

	Name	Definition	Description

	Name	Definition	Description
1	TPP	Third‑Party Provider	Initiates account‑information or payment‑initiation consent on behalf of an end user.
2	LFI	Licensed Financial Institution	Owns the customer’s account(s) and performs customer identification & OTP verification.
3	AlTareq App	Mobile Application	Hosts UX for onboarding, identification, consent approval, and redirects control back to TPP.

1.3 Scope

This document provides information on the following:

Technical integration tasks.
API descriptions and event notifications.
API security, including onboarding and provisioning.

User interface and experience design are out of scope of this document.

2. Integration Overview

2.1 Enrolment Flow

The enrolment of a User in CAAP is described in the API Hub documentation: CAAP - User Registration

During enrolment the follow actions will be undertaken:

Onboarding and Terms and Conditions: CAAP presents onboarding and terms and conditions screens.
- A User must accept terms and conditions once per device.
- Enrolment on a new device requires terms and conditions to be accepted.
User Identity Check: CAAP uses the Emirates Face Recognition (EFR) service to implement identity capture and provide a liveness check.

LFIs are provided with the Emirates ID value and expiration date through the LFI Ozone Connect APIs, as described in the sections below.

2.2 Consent Authorization Flow

The CAAP solution provides features for the granting of consent that simplifies the integration for TPPs and LFI with Nebras API Hub.

The main steps are shown in the Customer Experience below.

The high-level steps for the standardized consent flow, which typifies most operations, are as follows:

The User and TPP agree the data to be shared from a given LFI.
The User is redirected by the TPP to the CAAP mobile application.
The AlTareq CAAP mobile application authenticates the User and then collects the data required to authorize data access or service initiation.
The User authorizes access, selecting the data required to complete the process.
Access is granted to the TPP, who can then access the authorized data at the Nebras API Hub.

The high-level steps from a technical integration perspective are shown in the sequence diagram below.

Important

The steps below provide a complete overview of the consent flow.
Many steps are included for information, and do not need to be implemented by TPPs or LFIs.

The steps in the diagram are annotated in the following table.

	Step	Label	Purpose	Guidance

	Step	Label	Purpose	Guidance
1	1000	Consent to Data Sharing	Provides confirmation of consented operations to by User to TPP.	Following existing standards for consent request by TPPs. No CAAP-specific integration requirements.
2	1002	Get Participants Data	Get the list of Open Finance Framework participants to enable selection of LFI by User.	Following existing standards for retrieving participant data, where the Participant API provides the OpenID Discovery endpoint. No CAAP-specific integration requirements.
3	1003	Get Discovery Data	Get the OpenID Discovery data from the API Hub for the LFI.	Following existing standards for discovery. No CAAP-specific integration requirements.
4	1004	Lodge Unauthorized Consent	TPP Provides consent through a Pushed Authorization Request (PAR) to the API Hub at the correct LFI instance.	Follows existing standards for PAR. No CAAP-specific integration requirements.
5	1005	Provide Authorization Parameters	API Hub responds with a PAR response that includes the `request_uri` value.	Follows existing standards for PAR. No CAAP-specific integration requirements.
6	1006	Redirect to CAAP	TPP constructs a deep link based on requirements of FAPI 2.0 Security Profile that includes: `client_id` `request_uri` The deep link URL is based on the `authorization_endpoint` retrieved from discovery data.	TPP will create redirect URL based on discovery data, populating with required parameters. LFI configuration will implement an Authorization Server URL that can be resolved to CAAP. All other implementation details following existing standards.
7	2000	Retrieve LFI data	CAAP Application uses the deep link URL to correlate the LFI and retrieves LFI configuration data from CAAP Server.	The LFI configuration at the API Hub must conform to the CAAP integration requirements.
8	2001	Display LFI, Capture Biometric	The User is prompted for their registered biometric, based on previously completed enrolment steps.	No CAAP-specific integration requirements.
9	2002	Request Consent Authorization	The CAAP Server orchestrates the setup of consent at the API Hub, handling operations that LFIs would implement themselves if not using CAAP.	No CAAP-specific integration requirements.
10	3000	Request Data for Consent	CAAP Application requests data from the LFI Ozone Connect instance based on the consented operation. For example, for a payment CAAP requests the payment-eligible accounts using the `get /accounts` operation.	LFI must adhere to additional, CAAP specific guidance included in Ozone Connect API descriptions.
11	3003	Display Consent and Data Selection	CAAP Application displays consent and data selection to User.	No CAAP-specific integration requirements.
12	3004	Confirm Selection	User confirms consent and data selection.	No CAAP-specific integration requirements.
13	4000	Send Authorization Response	CAAP Application sends authorization of consent and data selection to CAAP Server.	No CAAP-specific integration requirements.
14	4001	Update Consent and Status	CAAP Server orchestrates consent authorization and update of data selection at API Hub.	No CAAP-specific integration requirements.
15	4003	Redirect User to TPP	User will be redirected back to TPP based on OpenID configuration at Trust Framework	No CAAP-specific integration requirements

2.3 Consent Management Flow

CAAP delivers consent management features that mirror the function of Consent Management Interfaces prescribed by the Open Finance Framework standards.

Consent management is delivered by the CAAP and the API Hub Consent Manager, with no specific requirements on TPPs or LFIs. Consent management flows are therefore not documented here.

3. TPP Requirements

The following sections provide the integration requirements for TPPs to successfully integrate with CAAP.

3.1 Onboarding

TPP must have onboarded through the existing Open Finance Framework onboarding process. No steps in this process are specific to CAAP.

Please refer to the Open Finance Framework for more details: Onboarding Process

3.2 Participants API

TPPs must allow Users to select the LFI who holds their bank accounts or insurance policies and with whom the User wishes to authorize access. LFI information is retrieved using the Participants API, which is part of the Open Finance Trust Framework. The Participants API is standardized across the Open Finance Framework, and the AlTareq CAAP solution does not require an alternative integration pattern.

Please refer to the Raidiam API documentation for more details: https://docs.connect.raidiam.io/find-data-providers-via-public-api

3.3 Discovery Endpoint

Participant data from the Participants API provides a link to the Discovery Endpoint for a given LFI, with particular focus on the following properties:

pushed_authorization_request_endpoint: The endpoint to which consents are sent.
authorization_endpoint: Provides the root URL for the LFI authorization endpoint.

The Discovery Endpoint mechanism is standardized across the Open Finance Framework, and the AlTareq CAAP solution does not require an alternative integration pattern.

3.4 Pushed Authorization Requests

TPPs must create consents as a Pushed Authorization Request (PAR), in accordance with the requirements of the FAPI 2.0 Security Profile. PAR is standardized across the Open Finance Framework, and the AlTareq CAAP solution does not require an alternative integration pattern.

Please refer to the Open Finance Framework standards for more details: PAR OpenAPI Description (v2.0)

3.5 Deep Linking

TPPs must construct a link by which to redirect the User to the CAAP Application which, as described above, contains the client_id and request_uri values.

The domain name of the deep link will be prefixed caap, which will allow the CAAP Application to resolve the URL.

An example URL is as follows: https://<base-url>/<provider-id>?client_id=1a703edb-b138-4fae-99aa-8348d418f296&response_type=code&scope=openid&request_uri=urn:ietf:params:oauth:request_uri:0abc06ab-5422-4aed-a1b8-ec5e4e4e6b90

Where:

client_id is the OAuth 2.0 Client ID held at the Trust Framework for the TPP.
response_type denotes Authorization Code flow, through the use of the value code.
scope is the OAuth 2.0 scope, and will be set by the TPP based on the values prescribed in the Open Finance Framework standards.
request_uri is the same value returned in the PAR response, prefixed with urn:ietf:params:oauth:request_uri:.

3.6 CAAP Application not Installed

If the deep link cannot be resolved an interstitial page is rendered in the default browser to allow the User to install the CAAP Application.

The interstitial page will detect the operating system and present the appropriate application store icon to allow the User to install the CAAP Application.

After install the interstitial will relaunch the original deep link through App Links or Universal Links as appropriate. The User be required to complete the enrolment flow described above.

3.7 Callbacks

The TPP must registered appropriate redirect_uri values in the Trust Framework to complete authorization. Redirects forms part of Authorization Code flow, and is implemented in accordance with the FAPI 2.0 Security Profile. Authorization Code flow is standardized across the Open Finance Framework, and the AlTareq CAAP solution does not require an alternative integration pattern.

4. LFI Requirements

The following sections provide the integration requirements for LFIs.

4.1 Onboarding

LFIs must have onboarded through the existing Open Finance Framework onboarding process: Onboarding Process

4.2 Ozone Connect User Operations APIs

4.2.1 User Enrolment

LFIs must implement the Ozone Connect User Operations API.

The User Operations API provides the means for Users enrolling in CAAP to link their identity to a one-or-more LFIs.

The API provides three key functions:

The registration of the User at the LFI, including the means for the a given LFI to issue a challenge to a User through, for example, an OTP.
The means to challenge a given User outside the registration flow.
The de-registration of a User when they uninstall CAAP or no longer want to be integrated with a given API.

Important

Personal Identifiable Information (PII) captured by CAAP through EFR is encrypted using public key encryption, encrypted using the LFI encryption key registered in the Trust Framework, and is securely transmitted to the LFI.
Only the LFI receiving the captured PII will be able to decrypt the registration data.
The approach to implementing public key encryption, through JSON Web Encryption, is described in this Knowledge Base article: How should PII be encrypted using JSON Web Encryption (JWE)?

Please refer to API Hub documentation for more details:

4.2.2 User Consent

CAAP supports LFIs by providing consent authorization services using the existing API Hub APIs. The granting of consent for either data sharing or service initiation follows a prescribed flow, which includes invoking Ozone Connect data sharing APIs to retrieve available bank accounts or insurance policies.

Please refer to the API Hub documentation for more details:

CAAP - Consent Authorization

4.2.3 PII Decryption

PII is protected by public key encryption when transmitted by TPPs, and can only be decrypted by an LFI that holds the private key. CAAP has no access to this data unless it is decrypted by the LFI.

LFIs must therefore implement an API operation in their Ozone Connect implementation that allows PII to be decrypted on request by the CAAP Resource Server, so that it can be used in the relevant consent flows when there is a requirement to display the data to the User.

Note

Decryption is a requirement for the User Enrolment flow, as PII captured at the CAAP Application and Resource Server through EFR is transmitted to the LFI encrypted.
LFIs can therefore reuse the functionality provided for this feature, as the public key encryption mechanism ensures the LFI will always decrypt with the same private key, referenceable by the ecosystem.