Note

All articles on FDX contain references to the Cloudentity platform and assume that Cloudentity provides the API security profile, OAuth and consent capabilites at the data providers end.

FDX Consent Management

A crucial aspect of the FDX specification is not only the ability to request and grant consents but also effective consent management. Consent management encompasses the maintenance and modification of existing consents. Upholding the principles of Control, Access, Traceability, and Transparency outlined by FDX, the consent management process must be accessible to both Fintech Application users and Financial Institutions that share data with these applications. This ensures that all stakeholders have the necessary tools and visibility to manage consents in accordance with regulatory requirements.

Note

If you want to learn more about FDX consent grant flow please follow our Consent APIs guide.

According to the FDX specification, consumers should have the ability to view comprehensive details of consent grants, including the permissions granted to Fintech Applications and the duration of the grants. They should also be able to revoke consent to prevent data sharing with Fintech Applications. Once a revocation is completed, users should be able to retrieve information about the initiator of the revocation and the reason behind it.

In terms of Consent Management APIs, let’s clarify the specific needs and which APIs are defined by the FDX specification.

1. Fintech Application Consent Management: As per FDX, Fintech applications are responsible for managing user consent grants within their own applications. They should provide users with a user interface to manage their consents. To access the Consent Management APIs, the Fintech application must authenticate itself (not the user) and can only access consent grants associated with its own client ID. The application needs to store consent IDs as there is no option to list all consents owned by the app for valid reasons.

2. Data Provider (Financial Institution or Data Access Platform) Consent Management: The APIs defined for Fintech applications cannot be used for self-management at the data provider’s (bank) side because these APIs do not support fetching consents created with multiple clients. While the API signatures may be the same, the policy applied to these APIs must be different to allow cross-client operations on consent grants. Additionally, there is a need for an API to list all user grants, which is not currently defined by the specification.

3. Bank Admin Consent Management: There is a third use case where bank administrators need to manage and list consent grants. They require more advanced filtering options, such as listing grants for specific users or filtering based on consent validity and parties involved.

It is important to note that consent APIs are not provided by default within an OAuth authorization server. Implementing FDX and utilizing an OAuth authorization server requires significant effort and complexity. By opting for the Cloudentity platform, the complexities of implementing consent management applications can be alleviated, providing a more streamlined and efficient solution.

This article primarily focuses on use cases 2 and 3, highlighting the integration and management of consent grants for data providers (banks) and their administrators. The specific needs and APIs associated with these use cases will be elaborated upon to provide a comprehensive understanding.

FDX Consent Management APIs

Cloudentity offers a comprehensive set of APIs to Financial Institutions, enabling them to manage all FDX consents granted for a specific Fintech Application. These APIs provide the capability to filter and view detailed information about consent grants. Additionally, Financial Institutions can utilize these APIs to revoke individual consents or revoke all consents granted for a particular Fintech Application.

By leveraging the APIs provided by Cloudentity, which will be further described in detail below, you will have the tools necessary to develop and integrate a Consent Self-Service application for customers. Moreover, you can create a Consent Admin application for Financial Institutions, allowing them to effectively manage all consent grants associated with the Fintech Applications connected to their institution.

Quickstart

Cloudentity offers FDX quickstart that can be used as reference application to build your own FDX consent management applications and showcases how you can integrate FDX workflows with the Cloudentity platform. Additionally, if you need guidance on how to use reference portals, see Using reference consent self-service and admin portals article.

Consent Listing

• List FDX Consents API specification

Sample request:

curl --request POST \
  --url https:///localhost:8443/default/default/servers/default/fdx/consents \
  --header 'Authorization: Bearer <BEARER_TOKEN>' \
  --data '{"limit":20,"resource":{"ids":["b14e1e714693bc00"],"resourceType":"ACCOUNT"}'

200 Response code should be returned with FDX consents list if the request is successful.

You can use this API to fetch a list of FDX consent grants. Returned consent list list can be narrowed by using filters provided in the request body. Especially you can filter consents by client_id to get all consents that were granted for a given Fintech Application (client). Another useful filter is resource where you can provide a resourceType, i.e. ACCOUNT and a list of resource ids which are values of the resource (in this case account numbers) that you are looking for. This enables you to get all consents granted for a given account.

There are also other filters available like limit, order, etc. that can be used for proper pagination implementation.

Single Consent Revocation

• Revoke FDX Consent API specification

Sample request:

curl --request DELETE \
  --url https:///localhost:8443/default/default/servers/default/fdx/consents/{consentID} \
  --header 'Authorization: Bearer <BEARER_TOKEN>' \
  --data '{"initiator":"DATA_ACCESS_PLATFORM","reason":"BUSINESS_RULE"}'

204 Response code should be returned with no response if a revocation is successful.

This API should be used when there is a need to revoke single consent by its id which has to be passed in URL. There are also two mandatory parameters: Initiator and Reason which have to be provided in request body. Initiator is a party that revokes a consent - available values are: DATA_ACCESS_PLATFORM, DATA_PROVIDER, DATA_RECIPIENT, INDIVIDUAL, MERCHANT, VENDOR. Reason is a reason of consent grant revocation - it can be one of: BUSINESS_RULE or USER_ACTION

Revocation of all consents for a given Fintech Application

• Revoke FDX Consents API specification

Sample request:

curl --request DELETE \
  --url https:///localhost:8443/default/default/servers/default/fdx/consents \
  --header 'Authorization: Bearer <BEARER_TOKEN>' \
  --data '{"RevocationDetails":{"initiator":"DATA_ACCESS_PLATFORM","reason":"BUSINESS_RULE"},"client_id":"fdx-developer-tpp"}'

204 Response code should be returned with number_of_consents_removed in response body if a revocation is successful.

You can use this API if for some reason there is a need to revoke all consents for the given Finantial Application. Finantial Application whose consents are to be removed can be specified by client_id parameter. Initiator and Reason which have to be provided in request body as for single consent grant revocation and will be applied to all revoked consents. In the response body you will get the nuumber of consent grants revoked.

List clients by authorization server

• List clients by authorization server

Sample request:

curl --request GET \
  --url https:///localhost:8443/api/system/default/clients/{wid} \
  --header 'Authorization: Bearer <BEARER_TOKEN>' \

200 Response code should be returned with Fintech application (client) list if the request is successful.

This API allows you to fetch all Fintech Applications registered within your FDX-compliant workspace in Cloudentity platform. It is worth to notice that within Cloudentity platform you may have more than one FDX compliant workspace (authorization server). You can use this API to display all Fintech Application for possible consent revocation. wid parameter is the identificator of Authorization Server (workspace).

Client Application Authentication API

• OAuth 2.0 token endpoint

You must be able to authenticate your Application to Cloudentity when making your API requests. Use this API to obtain Access Token needed by all APIs described above. The client application that you create in Cloudentity platform must be created within the System workspace for your tenant (as you will be using System level APIs) and have the manage_openbanking_consents scope assigned. Additionally for List clients by authorization server API view_clients scope needs to be assigned.

Management applications overview and integration

Having all necessary APIs described we can build custom Consent Self Service Application and Consent Admin Application and integrate them with Cloudentity.

Consent Self Service Application

Consent Self Service Application must be of the confidential client type. It means Consent Self Service Application must be able to store client credentials securely. Such credentials are used in the client credentials OAuth grant flow. Remember to configure client credentials while registering Consent Self Service Application in Cloudentity System Workspace. Also do not forget to enable granting manage_openbanking_consents scope.

The example requests flow in consumer Self Service Application integrated with Cloudentity and using APIs described above can look like this:

Consent Admin Application

To build a Consent Self-Service Application, it is important to note that it should be of the confidential client type. This ensures that the application can securely store client credentials. These credentials are utilized in the client credentials OAuth grant flow. When registering the Consent Self-Service Application in the Cloudentity System Workspace, remember to configure the client credentials and enable the granting of the manage_openbanking_consents scope.

It’s worth mentioning that you will need to develop this application yourself. However, Cloudentity provides a reference application that can serve as a valuable resource and guide during the development process.

The example requests flow in Consent Admin Application integrated with Cloudentity and using APIs described above can look like this:

Summary

Above sections cover the APIs that Cloudentity makes available for you to easliy manage consent grants. FDX is still evolving to make consent management and all related notifications in this area smoother and more transparent for all parties involved. Now you have learned about of all the consent management related APIs to build a customized Consent Self Service and Consent Admin applications and a way how to integrate them with Cloudentity ecosystem.

Cloudentity offers a higly available SaaS region in North America. If you want to host the solution yourself, we offer the same binary and tools that we use to run our SaaS infrastructure to your DevOps team. Your team can run our high scale solution on the infrastructure of your choice. Read about all the offered deployment models here

Register for free to get access to a Cloudentity tenant and accelerate the FDX adoption journey with us!

try now