Skip to main content

Customer Data Right Arrangement Amendment

This article provides an overview of Consumer Data Right (CDR) consent (arragement) amendement process when an accredited data recipient wants to modify an existing data sharing consent obtained from a consumer

CDR Arrangement Amendment

An existing data sharing agreement between an Accredited Data Recipient (ADR) and a Data Holder (DH) consented by a consumer is termed as a CDR arrangement. cdr_arrangement_id is a unique identifier of the CDR arrangement related to the authorization which is internally mapped to a consumer and related data sharing details as part of a specific consumer consent. The ADR is not obliged to pass an existing arrangement ID when creating new consent. If a new concurrent consent is to be created, then a consent is established without a pre-existing arrangement ID. An arrangement ID needs to be passed by the ADR only when an existing consent is being revoked and amended in an atomic step such as extension or modification of the consent.

Amendment Workflow

Below sequence diagram depicts a consumer consent amendment flow initiated by ADR with a Pushed Authorization Request (PAR) to the SecureAuth endpoint along with the existing “cdr_arrangement_id” and the new consent scope and sharing duration that needs to be amended.

Amendment_Workflow.svg

API usage

To allow consent application to handle consent amendment workflows as depicted above, following SecureAuth APIs must be utilized by the custom consent application.

  • OAuth 2.0 token endpoint

    The custom consent application is configured within the regular CDR workspace and it is internally registered as an OAuth Client application within the tenant System workspace. This client application is automatically subscribed to manage_openbanking_consents scope. This client application credentials must be used to authenticate the client and fetch an OAuth access token. The client application credentials can be obtained from the CDR workspace itself after the consent application is registered.

    cdr_qs_consent_setup_acp

    This access token needs to be presented as Bearer token while calling the consent APIs for CDR within SecureAuth. API access is allowed for Bearer tokens that have the manage_openbanking_consents scope.

    In the above diagram, you can see that the consent application makes requests to the {tenantId}/system/oauth2/token in step #7 to fetch an access token to make requests to SecureAuth consent APIs.

    Tip

    When requesting tokens, it is a good practice to explicitly define the scopes you need. It is recommended that you limit the scope of your token by explicitly providing the manage_openbanking_consents as the value of the scope parameter.

    The consent application may cache this token for the validity of its lifetime to eliminate multiple network calls to refetch access token and can reuse this token while interacting with SecureAuth APIs

  • Get CDR arrangement

    Get CDR arrangement API is used to retrieve detailed information about the CDR arrangement from SecureAuth, as shown in step #9 in above sequence diagram. This API returns the previous cdr arrangement details as well as the new amended arrangement request in the API response. This will allow the consent application to show a difference in the arrangement consents to consumer to approve/deny.

    It is to be noted that the amending arrangement is a temporal request scope and is not persisted until user explictly accepts the amended consent. According to the CDR spec, the previous arrangement is still valid until the new one is finalized, so during an amendment flow the value of status field within the response is Authorised.

    Tip

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6

    CX Guidance

    It is the responsibility of consent application to work out new scopes, sharing period, accounts that needs to be displayed to consumer. From the API response, following data elements can be used to derive the UI data values

    • scopes with previous_cdr_arrangement.scope_grants against requested_scopes

    • sharing period with previous_cdr_arrangement.expiry against cdr_arrangement.expiry

    • accounts using existing previous_cdr_arrangement.account_ids against the get accounts API from data holder itself

  • Accept CDR arrangement

    Accept CDR arrangement API must be called by the Consent application to notify SecureAuth that the consumer has accepted the amended consent and authorized the data recipient's request. Once the amended arrangement is accepted, SecureAuth persists the new arrangement over the existing arrangement and retains the same arrangement id. This API is utilized in step #15 in the above sequence diagram.

    If the API call succeeds, the consent application receives the redirect_to parameter in the response. Consent applications must redirect the consumer to the URL provided as the value of the redirect_to parameter.

    Tip

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6.

  • Reject CDR arrangement

    Reject CDR arrangement API must be called by the Consent application to notify SecureAuth that the consumer has rejected the amended consent and has not authorized the data recipient's request. Once the amended arrangement is rejected, SecureAuth retains the existing arrangement and discards the requested amended arrangement changes. This API is utilized in step #21 in the above sequence diagram.

    If the API call succeeds, the consent application receives the redirect_to parameter in the response. Consent applications must redirect the consumer to the URL provided as the value of the redirect_to parameter.

    API access

    This API is protected with tokens that has manage_openbanking_consents scope, use the Bearer token obtained in step #8.

    This API requires login & login_state parameters obtained in step #6.

In this section: