Account Access Consents v3.0
- 1 Version Control
- 2 Endpoints
- 3 Data Model
- 3.1 Account Access Consents - Request
- 3.1.1 UML Diagram
- 3.1.2 Data Dictionary
- 3.2 Account Access Consents - Response
- 3.2.1 UML Diagram
- 3.2.2 Data Dictionary
- 3.1 Account Access Consents - Request
- 4 Usage Examples
Version Control
Version | Date | Author | Comments |
|---|---|---|---|
3.0-draft1 | 18-Apr-2018 | OB R/W API Team | Initial draft for Version 3.0 |
3.0-draft3 | 18-May-2018 | OB R/W API Team | renamed "Account Request" to "Account Access Consent" renamed AccountRequestId to ConsentId renamed OBReadRequest1 to OBReadConsent1 renamed OBReadResponse1 to OBReadConsentResponse1 |
3.0-draft4 | Jun 4, 2018 | OB R/W API Team | Clarified use of Idempotency Key in endpoint table. |
3.0-draft5 | Jun 13, 2018 | OB R/W API Team | Updated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66 |
3.0-draft6 | Jul 3, 2018 | OB R/W API Team | No Change |
3.0-draft7 | Jul 17, 2018 | OB R/W API Team | No Change |
3.0-RC2 | Jul 19, 2018 | OB R/W API Team | No Change |
3.0-RC3 | Aug 6, 2018 | OB R/W API Team | No Change |
3.0 | Sep 7, 2018 | OB R/W API Team | This is the baseline version. No change from RC3. |
Endpoints
Resource | HTTP Operation | Endpoint | Mandatory? | Scope | Grant Type | Idempotency Key | Parameters | Request Object | Response Object | |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | account-access-consents | POST | POST /account-access-consents | Mandatory | accounts | Client Credentials | No |
| OBReadConsent1 | OBReadConsentResponse1 |
| 2 | account-access-consents | GET | GET /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | No |
|
| OBReadConsentResponse1 |
| 3 | account-access-consents | DELETE | DELETE /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | No |
|
|
|
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:
| Status | Status Description |
|---|---|---|
1 | AwaitingAuthorisation | The account access consent is awaiting authorisation. |
After authorisation has taken place the account-access-consent resource may have these following statuses.
| Status | Status Description |
|---|---|---|
1 | Rejected | The account access consent has been rejected. |
2 | Authorised | The account access consent has been successfully authorised. |
3 | Revoked | The 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:
| Status | Status Description |
|---|---|---|
1 | Rejected | The account access consent has been rejected. |
2 | AwaitingAuthorisation | The account access consent is awaiting authorisation. |
3 | Authorised | The account access consent has been successfully authorised. |
4 | Revoked | The 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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes |
|---|---|---|---|---|---|
OBReadConsent1 |
| OBReadConsent1 |
| OBReadConsent1 |
|
Data | 1..1 | OBReadConsent1/Data |
| OBReadData1 |
|
Permissions | 1..n | OBReadConsent1/Data/Permissions | Specifies 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. | OBExternalPermissions1Code | ReadAccountsBasic |
ExpirationDateTime | 0..1 | OBReadConsent1/Data/ExpirationDateTime | Specified date and time the permissions will expire. | ISODateTime |
|
TransactionFromDateTime | 0..1 | OBReadConsent1/Data/TransactionFromDateTime | Specified start date and time for the transaction query period. | ISODateTime |
|
TransactionToDateTime | 0..1 | OBReadConsent1/Data/TransactionToDateTime | Specified end date and time for the transaction query period. | ISODateTime |
|
Risk | 1..1 | OBReadConsent1/Risk | The 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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes |
|---|---|---|---|---|---|
OBReadConsentResponse1 | OBReadConsentResponse1 | OBReadConsentResponse1 |
|
|
|
Data | 1..1 | OBReadConsentResponse1/Data | OBReadDataConsentResponse1 |
|
|
ConsentId | 1..1 | OBReadConsentResponse1/Data/ConsentId | Unique identification as assigned to identify the account access consent resource. | Max128Text |
|
CreationDateTime | 1..1 | OBReadConsentResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime |
|
Status | 1..1 | OBReadConsentResponse1/Data/Status | Specifies the status of consent resource in code form. | OBExternalRequestStatus1Code | Authorised |
StatusUpdateDateTime | 1..1 | OBReadConsentResponse1/Data/StatusUpdateDateTime | Date and time at which the resource status was updated. | ISODateTime |
|
Permissions | 1..n | OBReadConsentResponse1/Data/Permissions | Specifies 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. | OBExternalPermissions1Code | ReadAccountsBasic |
ExpirationDateTime |