Security has always been the primary focus are for Open Banking.

• Bank level Security: Open Banking uses rigorously tested software and security systems. You’ll never be asked to give access to your bank login details or password to anyone other than your own bank or building society.

• Accreditation: Only third party providers regulated by the CBB can use Open Banking.

• User/ Customer is always in charge: you choose when, for what purpose and for how long, you give access to your data.

• Existing Bahrain Regulations: All the existing Bahrain regulations for data security, storage, dispute etc. will continue to be applicable to Open Banking services as well.

No. You will only use Open Banking if you give permission to an accredited third party provider. It will always be your choice – you need to give your explicit consent.

Yes. The user/customer needs give an explicit consent to use the Open Banking services of a third party provider. Amongst other things, the consent will clearly state the purpose for which it is granted and the time period for which it will be used.

You decide what information you wish to share with which third party. You choose which accredited third party provider you want to use. The ultimate control of your information will always be with you.

Access to data is driven by consent and the purpose which access was granted in first place. There are 2 ways in which you can stop giving access to your data:-

• Go to the accredited third party’s app or website, and withdraw your consent directly with them

• Contact your bank to let them know you no longer want the accredited third party’s app or website to have access to your information

Data can only be stored by the accredited third party providers for the purpose for which it was accessed under an explicit consent. Hence, once you cancel/revoke access to your data, the accredited third party provider has to delete that data.

No. You’ll always need to approve any payment made from your account. No payment can be made without your authorization.

If money has been taken from your account without your authorization, contact your bank as soon as you notice. Depending on the circumstances, they may be able to refund your money back.

Contact the bank or third party provider you believe have misused your data immediately. If you think you have been a victim of identity theft, immediately report it to your bank. 

Only accredited third party providers and ASPSPs are allowed to offer Open Banking services in Bahrain.
Anyone who wishes to receive user/customer data to offer products or services to users/customers must be accredited with the CBB.
To become accredited, a person must apply to the CBB. The CBB will review the application and duly advise the applicant in writing when it has:

• Granted the application without conditions;

• Granted the application subject to conditions specified by the CBB; or

• Refused the application, stating the grounds on which the application has been refused and the process for appealing against that decision

Accreditation criteria has been laid down and explained in detail in the Authorization Module of Volume 5 of CBB rulebook.

Anyone who wishes to know about the accreditation of a third party provider may do so by checking the list of accredited third party providers on the licensing directory available on the CBB website.

The CBB may amend or revoke a license in any of the following cases:

• 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

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 3.0.0 (also known as Open API) : http://swagger.io/

ISO 20022

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:

• 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).

• We will modify ISO 20022 elements where the existing standard does not cater for an API context (such as filtering, pagination etc.).

An idempotency key is used to guard against the creation of duplicate resources when using the POST API endpoints (where indicated).

If an idempotency key is required for an API endpoint:

• The x-idempotency-key provided in the header must be at most 40 characters in size. If a larger x-idempotency-key length is provided, the ASPSP must reject the request with a status code is 400 (Bad Request).

• The AISP/PISP must not change the request body while using the same x-idempotency-key. If the AISP/PISP changes the request body, the ASPSP must not modify the end resource. The ASPSP may treat this as a fraudulent action.

• The ASPSP must treat a request as idempotent if it had received the first request with the same x-idempotency-key from the same AISP/PISP in the preceding 24 hours.

• The ASPSP must not create a new resource for a POST request if it is determined to be an idempotent request.

• The ASPSP must respond to the request with the current status of the resource (or a status which is at least as current as what is available on existing online channels) and a HTTP status code of 201 (Created).

• The ASPSP may use the message signature, along with the x-idempotency-key to ensure that the request body has not changed.

If an idempotency key is not required for an API endpoint:

• The ASPSP must ignore the idempotency key if provided.

The APIs require TLS 1.2 Mutual Authentication and this may 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 AISP/PISP's private key and a response would be signed by the ASPSP's private key.

Not all API requests and responses are signed. Whether message signing is mandatory, supported or not supported is documented along with each API.

Message encryption is implemented through JSON Web Encryption (JWE).

The approach differs from message signing in that:

• The entire request or response payload is delivered in the form of an encrypted JWT.

• The definition of a given request or response in the Swagger specification represents the decrypted payload.

• The JWE will not be represented in its encrypted form in the Swagger specifications.

• Sending or expecting to receive an encrypted payload is denoted by setting the Accept or Content-type header to application/jose+jwe.

If an ASPSP does not support message encryption then should reject any requests with a Content-type or Accept headers that indicate that message encryption is required.

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.

The functionality, endpoints and fields within each resource are categorised as 'Mandatory', 'Conditional' or 'Optional'.

Mandatory

Functionality, endpoints and fields marked as Mandatory are required in all cases for regulatory compliance and/or for the API to function and deliver essential customer outcomes.

For functionalities and endpoints:

• An ASPSP must implement an endpoint that is marked Mandatory.

• An ASPSP must implement functionality that is marked Mandatory.

For fields:

• A AISP/PISP must specify the value of a Mandatory field.

• An ASPSP must process a Mandatory field when provided by the AISP/PISP in an API request.

• An ASPSP must include meaningful values for Mandatory fields in an API response.

Conditional

Functionality, endpoints and fields marked as Conditional may be required in some cases for regulatory compliance (for example, if these are made available to the USER/CUSTOMER in the ASPSP's existing Online Channel, or if ASPSPs (or a subset of ASPSPs) have been mandated by a regulatory requirement).

For functionalities and endpoints:

• An ASPSP must implement functionality and endpoints marked as Conditional if these are required for regulatory compliance.

For fields:

• All fields that are not marked as Mandatory are Conditional.

• A AISP/PISP may specify the value of a Conditional field.

• An ASPSP must process a Conditional field when provided by the AISP/PISP in an API request, and must respond with an error if it cannot support a particular value of a Conditional field.

An ASPSP must include meaningful values for Conditional fields in an API response if these are required for regulatory compliance.

Optional

Functionality and endpoints marked as Optional are not necessarily required for regulatory compliance but may be implemented to enable desired customer outcomes.

For functionalities and endpoints:

• An ASPSP may implement an Optional endpoint.

• An ASPSP may implement Optional functionality.

For fields:

• There are no Optional fields.

For any endpoints which are implemented by an ASPSP, the fields are either Mandatory or Conditional.

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - https://tools.ietf.org/html/rfc7158#section-8.1)

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

All date-time fields in responses must include the timezone. For Example:

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:

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

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.

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

• https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234

• https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234/transactions

The following are the HTTP response codes for the different HTTP methods, across all Read/Write API endpoints.

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

ASPSPs must respond with error response in the OAuth/OIDC flow with mandatory alignment of the error codes to those specified in OpenID Connect Core Specification Section 3.1.2.6.

ASPSPs must respond with Open Banking Error Response Structure for all errors during API Calls.

An ASPSP must provide limited support of filtering on GET operations 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.

An ASPSP MAY provide a paginated response for GET operations 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.

Archiving of resources will be for ASPSPs to define based on their internal Legal and Regulatory requirements.

A number of resources in the specification include a section for Supplementary Data. This is intended to allow ASPSPs to accept or provide information in a request or response that is not catered for by other sections of the resource definition.

The Supplementary Data section is defined as an empty JSON object in the specification.

Wherever used, an ASPSP must define and document (on their developer portal) their own structure, usage and (mandatory/optional) requirements for Supplementary Data.

An ASPSP must not use Supplementary Data if an element already exists in the OBF standard that fulfils the requirement.

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

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 provides a malformed request to the ASPSP in an attempt to setup an Account Request.

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 provides a (valid) access token which does not have a valid scope (or link to the correct Permissions) to Request Data.

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

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 Flow fails to succeed due to the USER/CUSTOMER providing invalid credentials to the ASPSP, resulting in no Authorization Code being generated.

Feel free to visit our confluence page for more updates. CBB will update this page on a periodic basis.

Feel free to write to us at bobf@cbb.gov.bh for inquiry or feedback you may have related to Open Banking.