/
Account and Transaction API Specification - v1.1.0

Account and Transaction API Specification - v1.1.0

Version Control

VersionDateAuthorComments
1.0.023 Jun 2017Open Banking Read/Write API Team

This is the Baseline version. No Changes from v1.0-rc4.

1.1.031 Aug 2017Open Banking Read/Write API Team

Includes 9 fixes, 5 clarifications and 14 enhancements. Please see the release note for details. Changes from v1.1-rc2: More explicit wording around Non-Repudiation not to be implemented for v1.x

Release Note

This release note explains what's new in The Account and Transaction API Specifications v1.1.0.

Fixes

  • In Accounts Transactions sequence diagram, removed Step 4 Request data response to the PSU.

  • Corrected the case for Links.First, Links.Last, Links.Next, Links.Prev, Links.Self and Meta.TotalPages (updated Basics/Pagination, Basics / Return & Error Codes / 400 (Bad Request) v/s 404 (Not Found), and Data Model / High Level Payload Structure / Response Structure).
  • Removed special characters in the Frequency field for Data Model / Data Payload - Resources / Standing Orders / Data Dictionary.
  • Corrected the Pattern for the ActiveOrHistoricCurrencyCode class from [A-Z]{3,3} to ^[A-Z]{3,3}$ to limit the field to 3 characters.
  • Corrected the Pattern for the CountryCode class to be specified as ^[A-Z]{2,2}$ instead of [A-Z]{2,2} to limit the field to 2 characters.
  • In Usage Examples, have corrected "AwaitingAuthentication" to "AwaitingAuthorisation"
  • Updated Usage Example for /products endpoint to align with Data Dictionary.
  • Updated Pagination Response JSON payload to correctly separate one of the JSON properties by inclusion of a comma.
  • Corrected a mis-spelling from "UFT-8" to "UTF-8".

Clarifications

  • Added details and updated examples on the various date formats used outside of the JSON payload (updated Examples, Basics / Date formats, and Basics / Non-repudiation / Process for signing a payload).
  • Clarified that Timezone offsets of -00:00 are not permitted in ISO-8601 (updated Examples, and all default dates in Data Model / Data payload - resources).
  • Clarified that all dates in HTTP headers are represented as RFC 7231 Full Dates. For example: Sun 3 Sep 2017 19:43:31 UTC
  • Clarified that a status of 403 should not be used to indicate a time-out of the access token, and that a 403 indicates that re-authentication of the PSU will not help.
  • Clarified that digital signatures must NOT be implemented for v1.x specification.

Enhancements

  • Metadata fields in the /transactions response now include an earliest available transaction date AND a latest available transaction date (updated Examples, Data Model / High Level Payload Structure / Response Structure / Meta, and default values specified in the Data Payload sections).
  • Added a new section to cater for reversals (Security & Access Control / Consent Authorization / Permissions / Reversing Entries).
  • Added a new section to specify the default character set as UTF-8 (Basics / Character Encoding). 
  • All datetime fields returned by the API must have the Timezone specified (updated Examples and added a new section Basics / Date Format).
  • Specified min and max page sizes for pagination (updated section on Basics / Pagination).
  • Sort Code and Account Number are now stored in the Account identification section together (in the Identification field), and a new SchemeName has been created for SortCodeAccountNumber (updated Examples, Data Model / Data Payload - Resources / Accounts / Data Dictionary, Data Model / Data Payload - Resources / Beneficiaries / Data Dictionary, Data Model / Data Payload - Resources / Standing Orders / Data Dictionary, and Data Model / Data Payload - Enumerations).

  • Extended the Standing Order Frequency pattern to include weekends and clarified pattern description (updated Data Model / Data Payload - Resources / Standing Orders / Data Dictionary).
  • Changed the BankTransactionCode to be the ISO 20022 code description, with all delimiters removed (updated Data Model / Data Payload - Resources / Transactions).
  • Add a Retry-After header for the HTTP 429 Too Many Requests response (updated Basics / Return & Error Codes, Basics / Headers / Response Headers, and Alternate Error Flows showing 429 as an optional implementation).
  • Added 405 and 406 as status codes (updated section on Basics / Response Headers).

  • Added clarifications to the Pagination section to state that the self link must be included in the response (Updated section Basic / Pagination).

  • Added a section describing resource URL path structures.

  • Added regex pattern for all Amount based fields under the Data Model / Data Payload. Removed pattern definition TotalDigits: 18 FractionDigits: 5.

  • Swagger Specification updated to include the Swagger Specification version number in the base of the URL (i.e. linked to this Specification).

Overview

This specification describes the Account Information and Transaction API flows and payloads.

The API endpoints described here allow an AISP to: 

  • Register an intent to retrieve account information by creating an "account request". This registers the data "permissions", expiration and transaction history timeframe the customer (PSU) has consented to provide to the AISP; and 
  • Subsequently retrieve account and transaction data

Document Overview

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions and principles that contributed to the specification.

Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.

Security & Access Control: Specifies the means for AISPs and PSUs to authenticate themselves and provide consent.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Data Model: Describes the data model for the API payloads.

Usage Examples: Examples for normal flows, and alternate flows.

Design Principles

RESTful APIs

The API adheres to RESTful API concepts where possible and sensible to do so.

However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.

References:

  • The highest level Data Description Language used is the JSON Schema : http://json-schema.org/
  • Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/
  • The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/ and 

Standards

The OBIE principles for developing the new API standards:

  • OBIE will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.
  • The initial scope of these Standards is limited to current OBIE scope - i.e., meeting CMA remedies. However, the intention is that the scope of the Standards will extend to either include or align to initiatives to cover a wider scope (i.e., PSD2).
  • The Standards currently being reviewed include ISO20022, and FAPI.
  • OBIE will favour developer/user experience over and above adoption of existing Standards, in order to create a more future proof Standard.
  • OBIE will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to creation of Standards around APIs and JSON payloads

ISO 20022

The CMA Order requires the CMA9 Banks to be aligned with the Regulatory and Technical Standards (RTS) under PSD2.

A previous draft of the EBA RTS required that the interface "shall use ISO 20022 elements, components or approved message definitions". In keeping with that requirement, the API payloads are designed using the ISO 20022 message elements and components where available.

The principles we have applied to re-use of ISO message elements and components are:

  • Where relevant - the API payloads have been flattened so that they are more developer friendly. This has been a request from the developer community, and the stakeholders involved in the design workshop
  • Only elements that are required for the functioning of the API endpoint will be included in the API payload. API endpoints are defined for specific use-cases (not to be generically extensible for all use-cases). Hence - only elements that are required for the account and transaction information scope are included in the Account Information API payloads for v1.0 (as this is the agreed scope for our v1.0 specification).
  • We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.). An example is having latitude and longitude in decimal format - as this is how developers will work with latitude and longitude; or using simple types (e.g., a single date-time field) instead of a complex type (e.g., a choice field with a nesting of date and time).

Extensibility

Version 1.0 of the API only caters to read access to account and transaction information for BCAs and PCAs.

However - where possible the APIs have been designed to be extensible - so they can in the future cover additional account types (e.g., card accounts) and operations (e.g., write access).

Idempotency

The Account Information and Transaction APIs will not be idempotent for v1.0.

Non-Repudiation

Important

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

Digital signatures will facilitate non-repudiation for Open Banking APIs. 

However, the solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Non-repudiation.

Unique Identifiers (Id Fields)

A REST resource should have a unique identifier (e.g. a primary key) that can be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that:

  • Some of the resources described in this specification do not have a primary key in the system of record.
  • For v1.0 it is not neccessary to individually address resources,

a decision has been made that Id fields will be specified for all resources - but be optional for all resources, except for the account resource.

The account resource needs to be addressed individually and must have a mandatory, unique and non-mutable identifier.

Scope

The APIs specified in this document provide the ability for AISPs to access a PSU's account and transaction information for domestic PCA and BCA accounts.

Out of Scope

This v1.0 specification does not cater for:

  • Write operations (the ability to create) standing orders, direct debits and beneficiaries.
  • Accounts other than PCAs and BCAs.
  • Progressive or changing consent - if the consent between the AISP and PSU changes, then the existing account-request object is deleted and a new account-request is created with the new consent/authorisation details.
  • The ability for the AISP to pre-specify the list of accounts that have been agreed with the PSU for consent/authorisation. At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time (e.g, customers adding or deleting accounts) affects the original agreed authorisation. 
  • The ability for the AISP to specify and "hints" for the types of accounts that have been agreed with the PSU for consent/authorisation (e.g., product or customer channel types). At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time affects the original agreed authorisation. 
  • Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are are not in the v1.0 specification.
  • Non-functional requirements and specification of caching and throttling.

Basics

Overview

The figure below provides a general outline of a account information requests and flow using the Account Info APIs.

Steps

Step 1: Request Account Information

  • This flow begins with a PSU consenting to allow an AISP to access account information data. 

Step 2: Setup Account Request

  • The AISP connects to the ASPSP that services the PSU's account(s) and creates an account-request resource. This informs the ASPSP that one of its PSUs is granting access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the AccountRequestId - which is the intent identifier).
  • This step is carried out by making a POST request to /account-requests endpoint
  • The setup payload will include these fields - which describe the data that the PSU has consented with the AISP:
    • Permissions - a list of data clusters that have been consented for access
    • Expiration Date - an optional expiration for when the AISP will no longer have access to the PSU's data
    • Transaction Validity Period - the From/To date range which specifies a transaction history period which can be accessed by the AISP
  • An AISP may be a broker for data to other 4th parties, and so it is valid for a customer to have multiple account-requests for the same accounts, with different consent/authorisation parameters agreed

Step 3: Authorise Consent

  • The AISP redirects the PSU to the ASPSP. The redirect includes the AccountRequestId generated in the previous step. This allows the ASPSP to correlate the account-request that was setup. The ASPSP authenticates the PSU. The ASPSP updates the state of the account-request resource internally to indicate that the account request has been authorised.
  • The principle we have agreed is that consent is managed between the PSU and the AISP - so the account-request details cannot be changed (with the ASPSP) in this step. The PSU will only be able to authorise or reject the account-request details in its entirety.
  • During authorisation - the PSU selects accounts that are authorised for the AISP request (in the ASPSP's banking interface)
  • The PSU is redirected back to the AISP.

Step 4: Request Data

  • This is carried out by making a GET request the relevant resource.
  • The unique AccountId(s) that are valid for the account-request will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token.

Sequence Diagram

Account Info - High Level Flow
participant PSU
participant AISP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
  
note over PSU, ASPSP Resource Server
    Step 1: Request account information
end note
PSU -> AISP: Get account/transaction information
 
note over PSU, ASPSP Resource Server
    Step 2: Setup account request
end note
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
AISP -> ASPSP Authorisation Server: Initiate Client Credentials Grant
ASPSP Authorisation Server -> AISP: access-token
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: POST /account-requests
ASPSP Resource Server -> AISP: HTTP 201 (Created), AccountRequestId
AISP -> PSU: HTTP 302 (Found), Redirect (AccountRequestId)
 
note over PSU, ASPSP Resource Server
Step 3: Authorise consent
end note
PSU -> ASPSP Authorisation Server: Follow redirect (AccountRequestId)
PSU <-> ASPSP Authorisation Server: authenticate
PSU <-> ASPSP Authorisation Server: SCA if required
PSU <-> ASPSP Authorisation Server: select accounts
ASPSP Authorisation Server -> PSU: HTTP 302 (Found), Redirect (authorization-code)
PSU -> AISP: Follow redirect (authorization-code)
AISP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
AISP -> ASPSP Authorisation Server: Exchange authorization-code for access token
ASPSP Authorisation Server -> AISP: access-token
 
  
note over PSU, ASPSP Resource Server
Step 4: Request data
end note
AISP <-> ASPSP Resource Server: Establish TLS 1.2 MA
AISP -> ASPSP Resource Server: GET /accounts
ASPSP Resource Server -> AISP: HTTP 200 (OK), List of accounts containing AccountId(s)
  
  
AISP -> ASPSP Resource Server: GET /accounts/{AccountId}/transactions
ASPSP Resource Server -> AISP: HTTP 200 (OK), List of transactions

Actors

ActorAbbreviationTypeSpecializesDescription
Payment Service UserPSUPersonN/AA natural or legal person making use of a payment service as a payee, payer or both (PSD2 Article 4(10))
Payment Service ProviderPSPLegal EntityN/AA legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11)
Account Servicing Payment Service ProviderASPSPLegal EntityPSP

An ASPSP is a PSP that provides and maintains a payment account for a payment services user (PSD 2 Article 4(15).

The CMA 9 are all ASPSPs.

Third Party Providers / Trusted Third PartiesTPPLegal EntityPSP

A party other than an ASPSP that provides payment related services.

The term is not actually defined in PSD2, but is generally deemed to include all payment service providers that are 3rd parties (the ASPSP and the PSU to whom the account belongs being the first two parties)

Payment Initiation Service ProviderPISPLegal EntityTPP

A TPP that provides Payment Initiation Services.

PSD2 does not offer a formal definition. Article 4(18) quite circularly defines a PISP as a PSP that provides Payment Initiation Services.

Account Information Service Provider

AISPLegal EntityTPP

A TPP that provides Account Information Services.

Again, PSD2 defines AISPs in Article 4(19) circularly as a PSP that provides account information services

Character Encoding

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1).

However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP should respond with an HTTP 400 (Bad Request) status code.

Date Formats

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:

2017-04-05T10:43:07+00:00


All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

Sun, 10 Sep 2017 19:43:31 UTC


JWT claims are expressed as a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. 

Resource URI Path Structure

The resources defined by these APIs can be addressed through a path structure consisting of the following parts:

  • An optional ASPSP specific path prefix
  • The constant string "open-banking"
  • The version of the APIs expressed as /v[major-version].[minor-version]/
  • The resource name

Examples:

/superbank/open-banking/v1.1/payments

/open-banking/v1.0/payments

/apis/open-banking/v1.1/payments

Headers

Request Headers

The following headers SHOULD be inserted by the TPP in each API call:

Header ValueNotesPOSTGETDELETE
x-fapi-financial-id

The unique id of the ASPSP to which the request is issued.

The unique id will be issued by OB.

MandatoryMandatoryMandatory
x-fapi-customer-last-logged-time

The time when the PSU last logged in with the TPP.

OptionalOptionalOptional
x-fapi-customer-ip-address

The PSU's IP address if the PSU is currently logged in with the TPP.

OptionalOptionalOptional
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

If provided, the ASPSP must "play back" this value in the x-fapi-interaction-id response header.

OptionalOptionalOptional
Authorization

Standard HTTP Header; Allows Credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

MandatoryMandatoryMandatory
Content-Type

Standard HTTP Header; Represents the format of the payload being provided in the request.

This must be set to application/json.

MandatoryDo not useDo not use
Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.

If set, it must have the value application/json.

If set to any other value, ASPSP must respond with a 406 Not Acceptable.

OptionalOptionalOptional
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.xNot for v1.xNot for v1.x

(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)

Whether the PSU is present or not-present is identified via the x-fapi-customer-ip-address header. If the PSU IP address is supplied, it is inferred that the PSU is present during the interaction.

The implications to this are:

  • ASPSPs will need to rely on AISPs assertion.
  • As agreed at TDA (18/05) It will be up to the ASPSPs to interpret the 4-times customer not present rule - to be within the “spirit” of the RTS requirement.
  • This is dependent on GDPR considerations on the AISP passing a PSU's IP address to an ASPSP.

Response Headers

Header ValueNotesMandatory ?
Content-Type

Standard HTTP Header; Represents the format of the payload returned in the response.

The ASPSP must return Content-type: application/json as a content header in response to requests that return a HTTP body (all post and get requests)

Conditionally Mandatory
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

Mandatory for requests that contain a payload.

A policy decision is under consideration on whether API requests and responses will be digitally signed to provide a simpler means of non-repudiation.

This header will only be applicable if the policy decision is to implement non-repudiation through digital signatures.

Not for v1.x
x-fapi-interaction-id

An RFC4122 UID used as a correlation id.

This must be the same value provided in the x-fapi-interaction-id request header.

Mandatory if provided in the request.

Conditionally Mandatory
Retry-After


Header indicating the time (in seconds) that the TPP should wait before retrying an operation.

The ASPSP should include this header along with responses with the HTTP status code of 429 (Too many requests).

Optional

Return & Error Codes

The following are the HTTP response codes for the different HTTP methods - across all Account Info API endpoints.

Situation

HTTP Status

Notes

Returned by POSTReturned by GETReturned by DELETE
Query completed successfully200 OK
NoYesNo
Normal execution. The request has succeeded.201 CreatedThe operation results in the creation of a new resource.YesNoNo
Delete operation completed successfully204 No Content
NoNoYes

Account Request has malformed, missing or non-compliant JSON body or URL parameters

400 Bad RequestThe requested operation will not be carried out.YesNoNo

Authorization header missing or invalid token

401 Unauthorized

The operation was refused access.

Re-authenticating the PSU may result in an appropriate token that can be used.

YesYesYes

Token has incorrect scope or a security policy was violated.

403 Forbidden

The operation was refused access.

Re-authenticating the PSU is unlikely to remediate the situation.

YesYesYes
The TPP tried to access the resource with a method that is not supported.405 Method Not Allowed
YesYesYes
The request contained an accept header that requested a content-type other than application/json and a character set other than UTF-8406 Not Acceptable
YesYesYes
The operation was refused as too many requests have been made within a certain timeframe.429 Too Many Requests

Throttling is a NFR.

The ASPSP should include a Retry-After header in the response indicating how long the TPP must wait before retrying the operation.

YesYesYes
Something went wrong on the API gateway or micro-service500 Internal Server ErrorThe operation failed.YesYesYes

An ASPSP MAY return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.

400 (Bad Request) v/s 404 (Not Found)

When a TPP tries to request a resource URL with an resource Id that does not exist, the ASPSP must respond with a 400 (Bad Request) rather than a 404 (Not Found).

E.g., if a TPP tries to GET /accounts/22289 where 22289 is not a valid AccountId, the ASPSP must respond with a 400.

When a TPP tries to request a resource URL that results in no business data being returned (e.g. a request to retrieve standing order on an account that does not have standing orders) the ASPSP must respond with a 200 (OK) and set the array to be empty.

If the TPP tries to access a URL for a resource that is not defined by these specifications (e.g. GET /card-accounts), the ASPSP may choose to respond with a 404 (Not Found).

If an ASPSP has not implemented an optional API, it must respond with a 404 (Not Found) for requests to that URL.

The table below illustrates some examples of expected behaviour:

SituationRequestResponse
TPP attempts to retrieve an account with an AccountId that does not existGET /accounts/1001400 (Bad Request)
TPP attempts to retrieve a resource that is not definedGET /credit-cards404 (Not Found)

TPP attempts to retrieve a resource that is in the specification, but not implemented by the ASPSP.

E.g., an ASPSP has chosen not to implement the bulk direct-debit endpoint

GET /direct-debits404 (Not Found)
TPP attempts to retrieve standing orders for an AccountId that does not existsGET /accounts/1001/standing-orders400 (Bad Request)
TPP attempts to retrieve standing orders for an AccountId that exists, but does not have any standing ordersGET /accounts/1000/standing-orders
200 OK
{
  "Data": {
    "StandingOrder": []
  },
  "Links": {
    "Self": "/accounts/1000/standing-orders/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

403 (Forbidden)

When a TPP tries to access a resource that it does not have permission to access, the ASPSP must return a 403 (Forbidden).

The situation could arise when:

  • The TPP uses an access token that does not have the approporiate scope to access the requested resource.
  • The TPP does not have a consent authorisation for the AccountId
    E.g., an attempt to access GET /accounts/2001 or /accounts/2001/transactions when the PSU has not selected AccountId 2001 for authorisation.
  • The TPP does not have a consent authorisation with the right Persmissions to access the requested resource.
    E.g., an attempt to access GET /standing-orders when the ReadStandingOrdersBasic permission was not included in the consent authorisation.
  • The TPP attempted to access a resource with an Id that it does not have access to.
    E.g., an attempt to access GET /account-requests/1001 where an account-request resource with Id 1001 belongs to another TPP.

When the TPP uses an access token that is no longer valid, the situation could potentially be remedied by asking the PSU to re-authenticate. This should be indicated by a 401 (Unauthorized) status code.

429 (Too Many Requests)

When a TPP tries to access a resource too frequently the ASPSP may return a 429 (Too Many Requests).  This is a Non Functional Requirement and is down to individual ASPSPs to decide throttling limits. 

This situation could arise when:

  • The TPP has not implemented caching, it requests transactions for a PSU account, and constantly re-requests the same transactions 
  • Similarly for any of the PSU information endpoints 

Pre-Conditions

The following pre-conditions must be satisfied in order to use these APIs:

Pre-conditions for TPPs

  1. The TPP must have completed onboarding on the Open Banking Directory
  2. The TPP must have registered one or more software statements with the Open Banking Directory. The software statement must have "accounts" as one of the required scopes.
  3. The TPP must have valid network and signing certificates issued by Open Banking.
  4. The TPP must have completed registration with each of the ASPSPs that it wants to transact with and have been issued with a client-id.

Pre-conditions for ASPSPs

  1. The ASPSP must have completed onboarding on the Open Banking Directory
  2. The ASPSP must have valid network and signing certificates issued by Open Banking

Idempotency

The API for creating an account-request resource is not idempotentOnce the API has been called, the state of the underlying resource changes.

If a time-out error occurs - then we would expect an AISP to create a new account-request resource - rather than try with the same resource.

Non-repudiation

Important

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

The solution for digital signatures (if required in a future release) has been agreed and the approach required to achieve this is described in Basics / Non-repudiation.

Overview

The APIs require TLS 1.2 Mutual Authentication and this can be used as a means of non-repudiation. However, it would be difficult to maintain digital records and evidence of non-repudiation if the API only relied on TLS 1.2.

A solution for non-repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content (as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.

The HTTP body would form an un-encoded payload as defined in RFC 7797.

The JWS would be signed using an algorithm that supports asymmetric keys.

A request would be signed by a TPP's private key  and a response would be signed by the ASPSP's private key.

OB Directory will provide and host the necessary certificates containing the corresponding public keys so that hte signature can be verified.

Specification

The TPP must sign the HTTP body of each API request that has an HTTP body. (e.g. GET requests do not have an HTTP body and are not signed.)

The ASPSP must sign the HTTP body of each API response that it produces which has an HTTP body.

The ASPSP should verify the signature of API requests that it receives before carrying out the request. If the signature fails validation, the ASPSP must respond with a 400 (Bad Request).

The ASPSP must reject any API requests that should be signed but do not contain a signature in the HTTP header with a 400 (Bad Request) error.

The TPP should verify the signature of API responses that it receives.

Process for signing a payload

Step 1: Identify the private key and corresponding signing certificate to be used for signing

The signer must use a private key that has a corresponding digital certificate (that contains the corresponding public key) issued by OB.

The signing certificate must be valid at the time of creating the JWS.

Step 2: Form the JOSE Header

The JOSE header for the signature must contain the following fields

Claim

Description

alg

The algorithm that will be used for signing the JWS.

The list of valid algorithms is here https://tools.ietf.org/html/rfc7518#section-3.1.

The algorithms that will be supported by OB will be specified in the future.

kid

This must match the certificate id of the certificate selected in step 1.

b64

This must have the boolean value false.

This indicates that the message payload is not base64 url encoded.

(See RFC 7797 - The "b64" header Parameter)

http://openbanking.org.uk/iat

This must be a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. 

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

http://openbanking.org.uk/iss

This must be a string containing the id of the TPP. This must match the dn of the signing certificate.

This is a private header parameter name. (See RFC 7515 - Private Header Parameter Names)

crit

This must be a string array consisting of the values "b64", "http://openbanking.org.uk/iat", "http://openbanking.org.uk/iss"

This indicates that the JWS signature validator must understand and process the three additional claims.

Step 3: Compute the JWS

The signer must compute the signature as a detached JWS as defined in