Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel2

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

...

titleWhat 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:

...

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
Requests

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.
If provided, the ASPSP must "play back" this value in the x-fapi-interaction-id response header.

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.
This must be set to application/json, except for the endpoints that support Content-Type other than application/json (e.g POST /file-payment-consents/{ConsentId}/file), the ASPSP must specify the available options on their developer portals.
This must be set to application/jose+jwe for encrypted requests.
The AISP/PISP may provide additional information (e.g. a 'q' value and charset).

Mandatory

Do not use

Do not use

Mandatory

Mandatory

Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.
If the AISP/PISP expects an unencrypted response, it must indicate that the only a JSON response is accepted (e.g. by setting the value to application/json) as a content header for all endpoints that respond with JSON.
If the AISP/PISP expects an encrypted response, it must indicate that the only a JWT response is accepted (e.g. by setting the value to application/jose+jwe) as a content header for all endpoints that respond with JSON.
For endpoints that do not respond with JSON (e.g. GET ../statements/{StatementId}/file), the ASPSP must specify the available options on their developer portals.
If set to an unacceptable value the ASPSP must respond with a 406 (Not Acceptable).
If not specified, the default is application/json.

Optional

Optional

Do not use

Optional

Optional

x-idempotency-key

Custom HTTP Header; Unique request identifier to support idempotency.
Mandatory for POST requests to idempotent resource end-points.
Must not be specified for other requests.

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.
Refer to resource specific documentation on when this header must be specified.

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.
The AISP/PISP may populate this field with the user-agent indicated by the User/Customer.
If 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.
The ASPSP must return Content-Type: application/json as a content header for all unencrypted endpoints, except the GET ../statements/{StatementId}/file and ../file-payment-consents/{ConsentId}/file endpoints, where it is up to the ASPSP to specify available options.
The ASPSP must return Content-type: application/jwe for all encrypted end-points.

Mandatory

x-jws-signature

Header containing a detached JWS signature of the body of the payload.
Refer to resource specific documentation on when this header must be returned. Where a signed response is indicated in the documentation this header should be returned for error responses where a response body is returned.

API specific

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.
The ASPSP must set the response header x-fapi-interaction-id to the value received from the corresponding fapi client request header or to a RFC4122 UUID value if the request header was not provided to track the interaction. The header must be returned for both successful and error responses.

Mandatory

Retry-After

Header indicating the time (in seconds) that the AISP/PISP 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

...

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. Expandtitle

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
titleWhat will be the error flow if the access token is missing or expired?

This 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 attempts to provide an expired or missing access token to the ASPSP in an attempt to Request Data

Image Removed

Expandtitleonly 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.

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.Image Removed

Expandtitle

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.Image Removed

Expandtitle

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.

Image Removed

Expandtitlemalformed request to the ASPSP in an attempt to setup an Account Request.

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. Expandtitle

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