Account Access Consents v3.1

Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.
3.1-draft1 OB R/W API Team

This is the initial draft version for 3.1.

Errata

  • Grammatical Fixes
3.1-draft2 OB R/W API Team

Draft2 Changes:

  • Updated example URLs to version 3.1.
3.1OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1.

Endpoints


ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotency KeyParametersRequest ObjectResponse Object
1account-access-consentsPOSTPOST /account-access-consentsMandatoryaccountsClient CredentialsNo
OBReadConsent1OBReadConsentResponse1
2account-access-consentsGETGET /account-access-consents/{ConsentId}MandatoryaccountsClient CredentialsNo

OBReadConsentResponse1
3account-access-consentsDELETEDELETE /account-access-consents/{ConsentId}MandatoryaccountsClient CredentialsNo


POST /account-access-consents 

The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.

  • This API effectively allows the AISP to send a copy of the consent to the ASPSP to authorise access to account and transaction information.
  • An AISP is not able to pre-select a set of accounts for account-access-consent authorisation. This is because the behaviour of the pre-selected accounts, after authorisation, is not clear from a Legal perspective.
  • An ASPSP creates the account-access-consent resource and responds with a unique ConsentId to refer to the resource.
  • Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

Account Access Consent Status

The PSU must authenticate with the ASPSP and authorise the account-access-consent for the account-access-consent to be successfully setup.

The account-access-consent resource that is created successfully must have the following Status code-list enumeration:


StatusStatus Description
1AwaitingAuthorisationThe account access consent is awaiting authorisation.

After authorisation has taken place the account-access-consent resource may have these following statuses.


StatusStatus Description
1RejectedThe account access consent has been rejected.
2AuthorisedThe account access consent has been successfully authorised.
3RevokedThe account access consent has been revoked via the ASPSP interface.

Status Flow

This is the state diagram for the Status.

GET /account-access-consents/{ConsentId}

An AISP may optionally retrieve an account-access-consent resource that they have created to check its status. 

Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

The usage of this API endpoint will be subject to an ASPSP's fair usage policies.

Account Access Consent Status

Once the PSU authorises the account-access-consent resource - the Status of the account-access-consent resource will be updated with "Authorised".

The available Status code-list enumerations for the account-access-consent resource are:


StatusStatus Description
1RejectedThe account access consent has been rejected.
2AwaitingAuthorisationThe account access consent is awaiting authorisation.
3AuthorisedThe account access consent has been successfully authorised.
4RevokedThe account access consent has been revoked via the ASPSP interface.

DELETE /account-access-consents/{ConsentId}

If the PSU revokes consent to data access with the AISP, the AISP must delete the account-access-consent resource with the ASPSP before confirming consent revocation with the PSU.

  • This is done by making a call to DELETE the account-access-consent resource.
  • Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.

Data Model

Account Access Consents - Request

The OBReadConsent1 object will be used for the call to:

  • POST /account-access-consents

UML Diagram

Notes:

  • The fields in the OBReadConsent1 object are described in the Consent Elements section.
  • No fields have been identified for the Risk section.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadConsent1
OBReadConsent1
OBReadConsent1
Data1..1OBReadConsent1/Data
OBReadData1
Permissions1..nOBReadConsent1/Data/PermissionsSpecifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadPAN
ReadParty
ReadPartyPSU
ReadProducts
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadConsent1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.
ISODateTime
TransactionFromDateTime0..1OBReadConsent1/Data/TransactionFromDateTimeSpecified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.
ISODateTime
TransactionToDateTime0..1OBReadConsent1/Data/TransactionToDateTimeSpecified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.
ISODateTime
Risk1..1OBReadConsent1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info.OBRisk2

Account Access Consents - Response

The OBReadConsentResponse1 object will be used for the call to:

  • GET /account-access-consents/{ConsentId}

And response to:

  • POST /account-access-consents

UML Diagram

Notes:

  • The OBReadConsentResponse1 object contains the same information as the OBReadConsent1, but with additional fields:
    • ConsentId - to uniquely identify the account-access-consent resource.
    • Status.
    • CreationDateTime.
    • StatusUpdateDateTime.
  • No fields have been identified for the Risk section.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodes
OBReadConsentResponse1OBReadConsentResponse1OBReadConsentResponse1


Data1..1OBReadConsentResponse1/DataOBReadDataConsentResponse1

ConsentId1..1OBReadConsentResponse1/Data/ConsentIdUnique identification as assigned to identify the account access consent resource.Max128Text
CreationDateTime1..1OBReadConsentResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime
Status1..1OBReadConsentResponse1/Data/StatusSpecifies the status of consent resource in code form.OBExternalRequestStatus1CodeAuthorised
AwaitingAuthorisation
Rejected
Revoked
StatusUpdateDateTime1..1OBReadConsentResponse1/Data/StatusUpdateDateTimeDate and time at which the resource status was updated.ISODateTime
Permissions1..nOBReadConsentResponse1/Data/PermissionsSpecifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.OBExternalPermissions1CodeReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadPAN
ReadParty
ReadPartyPSU
ReadProducts
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
ExpirationDateTime0..1OBReadConsentResponse1/Data/ExpirationDateTimeSpecified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.
ISODateTime
TransactionFromDateTime0..1OBReadConsentResponse1/Data/TransactionFromDateTimeSpecified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.
ISODateTime
TransactionToDateTime0..1OBReadConsentResponse1/Data/TransactionToDateTimeSpecified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.
ISODateTime
Risk1..1OBReadConsentResponse1/RiskThe Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info.OBRisk2

Usage Examples

Setup Account Access Consent - All Permissions Granted

Request

Response

Status - AwaitingAuthorisation

This is an example of a GET request which is made before the account access consent resource is authorised. 

Request

Response

Status - Authorised

This is an example of a GET request which is made after the account access consent resource is authorised.

Request

Response

Delete Account Access Consent

The DELETE /account-access-consents call allows an AISP to delete a previously created account-access-consent (whether it is currently authorised or not). The PSU may want to remove their consent via the AISP instead of revoking authorisation with the ASPSP.

This API call allows the PSU to revoke consent with the AISP, and for that consent to be reflected in authorisation with the ASPSP.

Request

Response

Setup Account Access Consent with Limited Permissions

Request

Response