Table of Contents | ||
---|---|---|
|
General
What is Bahrain Open Banking Framework (Bahrain OBF)?
...
Read access allows the data recipient to obtain copies of customers’ financial data and use it for such activities as data aggregation (for example – AIS - account aggregations services).
Write access allows data recipient to initiate payments on behalf of the user/customer (for example – PIS - payment initiation services).
Security and Privacy
Is Bahrain Open Banking safe?
...
Strong Customer Authentication or ‘SCA’ is authentication based on the use of three elements categorized as knowledge (something only the user knows [for example, a password]), possession (something only the user possesses [for example, particular cell phone and number]) and inherence (something the user is [or has, for example, a fingerprint or iris pattern]) that are independent, so the breach of one does not compromise the others, and is designed in such a way as to protect the confidentiality of the authentication data. For further information on elements of SCA or related exemptions, kindly refer to relevant Open Banking sections of the Rulebook.
Accreditation
Why should anyone apply for accreditation?
...
If the licensee fails to satisfy any of the license conditions;
If the licensee violates the terms of the CBB Rulebook;
If the licensee fails to start business within six months from the date of the license;
If the licensee ceases to carry out the licensed activity in the Kingdom;
The legitimate interests of the customers or creditors of a licensee required such amendment or cancellation
API Specification
...
What
...
All date-time fields in responses must include the timezone. For Example:
2020-04-05T10:43:07+03:00 2020-05-03T14:43:41Z |
---|
The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.
All dates in the query string are represented in ISO-8601 date-time format and must not include the timezone. For example:
2020-04-05T10:43:07 2020-04-05 |
---|
All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
Tue, 10 Mar 2020 19:43:31 GMT+03:00 |
---|
All dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.
//Wed, 12 Feb 2020 14:45:00 GMT+03:00 1581507900 |
---|
...
title | What will be the structure of resource URI path? |
---|
The path of the URI must follow the structure below
...
is the use of Unique Identifiers (Id Fields)?
A REST resource should have a unique identifier (e.g. a primary key) that may 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 these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.
An ASPSP that chooses to populate optional Id fields must ensure that the values are unique and immutable.
Are ASPSPs allowed to create their own enumeration when required?
Yes, ASPSPs can create their own enumerations. The Bahrain OBF Specification includes various fields of Enumerated data types, where either the values are fixed to the defined set of alternatives (i.e. Static Enumerations), or flexible with defined set of alternatives, and ASPSPs can use/extend these alternatives (i.e. Namespaced Enumerations).
When extending a namespaced enumeration:
ASPSPs must not publish an ASPSP-specific enumerated value if the existing Bahrain OBF guidelines defines the enumerated value.
ASPSPs must place such values in a namespace consisting of their two-letter country code (ISO 3166-1 Alpha-2 code), followed by a full-stop, followed by their name. e.g. BH.Bank1.enum1, where Bank1 is the bank name and enum1 is the extended enumeration.
What are the date formats used in the API?
All date-time fields in responses must include the time zone. For Example:
2020-10-05T10:43:07+03:00 2020-10-03T14:43:41Z |
The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.
All dates in the query string are represented in ISO-8601 date-time format and must not include the time zone. For example:
2020-10-05T10:43:07 2020-10-05 |
All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
Tue, 10 Oct 2020 19:43:31 GMT+03:00 |
All dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.
//Wed, 12 Oct 2020 14:45:00 GMT+03:00 1581507900 |
What will be the structure of resource URI path?
The path of the URI must follow the structure below
[participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource]
This consists of the following elements:
[participant-path-prefix]
An optional ASPSP specific path prefix
...
open-banking
The constant string "open-banking"
...
[version]
The version of the APIs expressed as /v[major-version].[minor-version]/.[resource-group]
The resource-group identifies the group of endpoints, to access the API (as "aisp", "pisp")
...
[resource]/[resource-id]
Details the resource
...
[sub-resource]
Details the sub-resource
...
An ASPSP must use the same participant-path-prefix and host name for all its resources.
Examples:
https://xyz.com/apis/open-banking/v1.1/pisp/domestic-payments
https://xyz.com/apis/open-banking/v1.1/aisp/account-access-consents
https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234/transactions
...
What are request headers?
Request Header is a HTTP header that contains information about the fetched request by the client.
Header Value | Notes | POST Requests | GET Requests | DELETE Requests | PUT Requests | PATCH |
x-fapi-auth-date | The time when the User/Customer last logged in with the AISP/PISP. e.g., x-fapi-auth-date: Mon, 11 |
...
October 2020 19:43:31 GMT+03:00. | Optional | Optional | Optional | Do not use | Optional | |
x-fapi-customer-ip-address | The User’s/Customer’s IP address if the User/Customer is currently logged in with the AISP/PISP. | Optional | Optional | Optional | Do not use | Optional |
x-fapi-interaction-id | An RFC4122 UID used as a correlation Id. | Optional | Optional | Optional | Optional | Optional |
...
Authorisation | 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. | Mandatory | Mandatory | Mandatory | Mandatory | Mandatory |
Content-Type | Standard HTTP Header; Represents the format of the payload being provided in the request. | Mandatory | Do not use | Do not use | Mandatory | Mandatory |
Accept | Standard HTTP Header; Determine the Content-Type that is required from the Server. | Optional | Optional | Do not use | Optional | Optional |
x-idempotency-key | Custom HTTP Header; Unique request identifier to support idempotency. | Optional | Do not use | Do not use | Do not use | Do not use |
x-jws-signature | Header containing a detached JWS signature of the body of the payload. | API specific | API specific | API specific | Mandatory | API specific |
x-customer-user-agent | The header indicates the user-agent that the User/Customer is using. |
...
an AISP/PISP mobile app, the AISP/PISP must ensure that the user-agent string is different from browser based user-agent strings. | Optional | Optional | Optional | Optional | Optional |
...
What are
...
response headers?
Response Header is a HTTP header that contains the responses to inbound HTTP requests.
Header Value | Notes | Mandatory |
...
Content-Type | Standard HTTP Header; Represents the format of the payload returned in the response. | Mandatory |
x-jws-signature | Header containing a detached JWS signature of the body of the payload. | API specific |
x-fapi-interaction-id | An RFC4122 UID used as a correlation Id. | Mandatory |
Retry-After | Header indicating the time (in seconds) that the AISP/PISP should wait before retrying an operation. | Optional |
...
Does GET operation
...
support filtering?
An ASPSP must provide limited support of filtering on GET operations operation that return multiple records.
The filter parameters, are always specific to particular field(s) of the resource, and follow the rules/formats defined under the resource's data dictionary.
In case of DateTime type filter parameters, values must be specified in ISO8601 format. If the DateTime contains a timezone, the ASPSP may ignore the timezone component.
The filter values will be assumed to refer to the same timezone as the timezone in which the resource is maintained. Expand
Does GET
...
operation support pagination?
An ASPSP MAY provide a paginated response for GET operations operation that return multiple records.
In such a situation, the ASPSP MUST:
If a subsequent page of resource records exists, the ASPSP must provide a link to the next page of resources in the Links.Next field of the response. The absence of a next link would indicate that the current page is the last page of results.
If a previous page of resource records exists, the ASPSP must provide a link to the previous page of resources in the Links.Prev field of the response. The absence of a prev link would indicate that the current page is the first page of results.
For a paginated responses, the ASPSP may ensure that the number of records on a page are within reasonable limits, the minimum and maximum level for number of records may be decided based on agreement between ASPSP and AISP/PISP.
Additionally, the ASPSP MAY provide:
A link to the first page of results in the Links.First field.
A link to the last page of results in the Links.Last field.
The total number of pages in the Meta.TotalPages field.
As with all other responses, the ASPSP MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.
This standard does not specify how the pagination parameters are passed by the ASPSP and each ASPSP may employ their own mechanisms to paginate the response.
If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.
ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.
Expand | ||
---|---|---|
| ||
This flow assumes that the following steps have been completed successfully:
The AISP attempts to provide an expired or missing access token to the ASPSP in an attempt to Request Data |
ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.
What will be the error flow if
...
the access token is missing or has expired?
The error flow assumes that the following Steps steps have been completed successfully:
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
The AISP provides a malformed request attempts to provide an expired or missing access token to the ASPSP in an attempt to setup an Account Request Data.
What will be the error flow if the access token scope is missing or invalid?
This The error flow assumes that the following Steps have been completed successfully:
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
The AISP provides a (valid) access token which does not have a valid scope (or link to the correct Permissions) to Request Data.
What
...
will be the error flow if
...
the request payload is incomplete or malformed?
The error flow assumes that the following Steps have been completed successfully:
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
The AISP provides a (valid) access token which is used to generate a burst of multiple requests to retrieve an Accounts resource.
The ASPSP may optionally choose to return a 429 Response.
What will be the error flow if
...
there is sudden burst of API requests?
This The error flow assumes that the following Steps have been completed successfully:
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
...
Further Information
How can I stay informed on new Open Banking updates or news?
The confluence pages will be updated on a periodic basis to keep the Open Banking participants informed on new developments.
Who can I reach out to in case of any general enquiry regarding Open Banking?
For any general enquiry on Open Banking, kindly submit the general enquiry form available on https://www.cbb.gov.bh/general-enquiry-form/
...
The AISP provides a (valid) access token which is used to generate a burst of multiple requests to retrieve an Accounts resource.
The ASPSP may optionally choose to return a 429 Response.
What will be the error flow if consent authorisation has failed?
The error flow assumes that the following Steps have been completed successfully:
Step 1: Request Account Information
Step 2: Setup Account Request
Step 3: Authorise Consent
Flow fails to succeed due to the USER/CUSTOMER providing invalid credentials to the ASPSP, resulting in no Authorisation Code being generated.
Further Information
How can I stay informed on new Open Banking updates or news?
The confluence pages will be updated on a periodic basis to keep the Open Banking participants informed on new developments. title Expand
Who can I reach out to in case of any general enquiry regarding Open Banking?
For any general enquiry on Open Banking, kindly submit the general enquiry form available on https://www.cbb.gov.bh/general-enquiry-form/
CENTRAL BANK OF BAHRAIN © 2020