Learn how authentication and authization work

The third party provider (TPP) consuming Arab Bank's transactional API initially submits an account request (POST /account-requests or POST /payment-initiation) on behalf of a user, which contains information about account permissions, transaction to and from date etc.

Once the TPP submits the account request, the user will have to authenticate with the bank using two-factor authentication, choosing the list of accounts they want to provide the permissions for, which will then provide the client application with a unique and time-bound access token. The TPP app can use this unique token to make calls to the bank on the behalf of the user, for accounts chosen by the user while providing consent.

Generally, these access tokens are specific to a single account request submitted by the TPP on behalf of a user.

For the accounts and payment APIs, users need to authenticate their Arab Bank accounts each time an API call is made because these API calls need to meet higher security requirements.

The end user authenticates the account and provides access to the app to carry out the transaction via a two-step verification on the bank site. The following steps are done to provide authentication:

  • TPP submits an account request using "client credentials" access token. (Client Credentials OAuth2.0 grant type)
  • The user is redirected to bank's server to provide consent for the account request TPP submitted.
  • The user is shown a log-in page, where the user logs-in with bank customer Id and password.
  • The user is shown the consent page based on account request submitted by TPP earlier. The user verifies the perfissions TPP asked for, and the user selects the account(s).
  • The bank then requests the user to verify this with a One Time Password (OTP), which is sent to the user’s registered mobile number.
  • Once the user enters the OTP, an access token specific to that account is generated, which the app can then use to make API calls and access Arab Bank's resources on behalf of the user. (Authorization Code OAuth2.0 grant type)

The user experience for logging into the user's account is identical to when the user chooses to log in with their Facebook or Google accounts.

 

Using APIs in your app

It starts once you create an app and provide the required details to enable support for the OAuth 2.0 three-legged flows, such as the callback/redirect url.

In order for the app to make any API calls, it will have to present its client ID (API key) and secret. This is to ensure that only authenticated apps can make API calls.

For accessing the accounts and payments APIs, the app will first make a call to the OAuth API (POST /token), so that the app can get an access token to access account(s) on behalf of the user. The OAuth APIs support both the implicit grant type wherein the access token is returned directly to the app once the user has authenticated. If the app wishes to keep the authentication more secure (which it should, unless it is a trusted app), then the app could also use the authorization code flow wherein a code is returned back to the app. It should then exchange it for an access token.

The two flows are differentiated by specifying the response_code parameter as ‘code id_token’ for the three-legged authorization code flow and as ‘token’ for the implicit grant.

The App can then use this access token to make the calls to the accounts/payments APIs. When the API is called, the customer and account information is retrieved from the access token and the account information is then presented to the user.

 

Account Access APIs

For accessing this API endpoint, the app will first make a call to the OAuth API to get a client_credential access token, then create an account request which will have the details of the access required.

The account request contains the information like account information permissions, the permission expiration time etc.

Once the Account request is created, the app requests for an access token for the account request created. While providing the consent, the user selects the list of accounts they want the app to get access to.

The app now gets an access token to access account(s) on behalf of the user. The OAuth APIs support both the implicit grant flow wherein the access token is returned directly to the app once the user has authenticated. If the app wishes to keep the authentication more secure (which it should), then the app could also use the authorization code flow wherein a code is returned back to the app and it should then exchange it for an access token.

The two flows are differentiated by specifying the response_code parameter as ‘code id_token’ for the three-legged authorization code flow and as ‘token’ for the implicit grant.

The App can then use this access token to make the calls to the accounts APIs. When the API is called, the customer information is retrieved from the access token and the account information is then presented to the user.

Accounts API Flow

 

Payment APIs

For accessing these API endpoints, the app will first make a call to the OAuth API to get a client_credential access token, then create a payment request which will have the details of the payment initiation.

The payment request contains the information like creditor details, debitor details, the amount to be transfered, merchant details etc.

Once the payment request is created, the app requests for an access token for the payment request made by the app. While providing the consent, the user selects the debit account through which the payment has to be made.

The app now gets an access token to submit one time single payment on behalf of the user. The OAuth APIs support both the implicit grant flow wherein the access token is returned directly to the app once the user has authenticated. If the app wishes to keep the authentication more secure (which it should unless it is a trusted app), then the app could also use the authorization code flow wherein a code is returned back to the app and it should then exchange it for an access token.

The two flows are differentiated by specifying the response_code parameter as ‘code’ for the three-legged authorization code flow and as ‘token’ for the implicit grant.

The App can then use this access token to submit the payment. When the API is called, the payment is submitted according to the payment request Id for which the access token was generated.

Payments API Flow

*The above diagrams illustrate the entire flow for Account information/Payment APIs. Do not be tricked by the complexity of the flow; the API handles the entire flow, and the user experience will be only a few clicks.

 

Open data APIs

Open data APIs are a category of APIs that provide non-customer specific information from a bank. These offer bank-specific information, such as ATM locations, products, Exchange rates, et cetera. These APIs are not subjected to user-level authentication. The only requirement to use these APIs is the API key obtained when you register an app.

 

Summary

The below image summarizes the flow in which a third party app needs to follow in order to access Arab Bank's customer-specific resources.

 

Nomenclature:

  • TPP: Trusted Third Party (Your Website or App)
  • ASPSP: Account Servicing Payment Service Provider (Arab Bank)
  • AT/RT: Access Token/Refresh Token
  • OB: Open Banking (Not relevant to Jordan - Not Required)
  • SSA: Software Statement Assertion (Not relevant to Jordan - Not Required)

 

Now that you understand authentication and authorization on a deeper level. You can try our APIs in the interactive API docs on our API catalogue. 

Make sure you have generated a public & private key for your registed app as explained on this quick guide.