OAuth Client Credentials Grant Type
-
API Security
Being a bank, RAKBANK places a lot of importance to information security and also the reason why we have multiple security policies protecting the data that is exchanged through our Open APIs. Not all security policies are applicable to our sandbox environment. For information about the different environments available for RAKBANK’s Open APIs, see Environments. The UAT and Production environments will always have all the API security policies enabled.
-
UAT & Production Environments
The following list of API security policies apply to our UAT & Production Environments
- IP Whitelisting
- Mutual SSL Authentication
- Digital Signature (JWS)
- Digital Encryption (JWE)
- API Key(s)
- OAuth2
IP Whitelisting
Confidential Client Applications can invoke the bank’s Open APIs only from whitelisted Public IP(s). The client would be required to share their list of Public IPs in the UAT and Production environments with the bank’s team.
Note: The SLA for the whitelisting is 2-4 working days.
Mutual SSL Authentication
Mutual SSL authentication between the client and the server is required for successful invocation of the Open APIs in UAT & Production environments. Only TLS 1.2 and higher versions are supported. The client would be required to generate their X509 private key and certificate, of minimum 2048 bits, and share the public certificate with the bank’s team.
Naming Convention Certificate Name {CN}_PublicKey_{ExpiryDateDDMMYY}.cer Note: The client needs to ensure that the server certificate verification is always turned on during SSL handshake when invoking our API URLs.
Digital Signature using JWS
JWS that stands for JSON Web Signature, is commonly used for signing JSON Web Tokens (JWT). At RAKBANK, we are using this open industry standard to validate the authenticity and integrity of a message sent by the client. Clients are expected to digitally sign the JSON request payloads, using JWS. The JWS output format supported is JSON Serialization. The signed payload should be further digitally encrypted using the JWE standard. For information on digital encryption of the request payload, see Digital Encryption using JWE. The JSON response payload of an API will be digitally signed and encrypted at RAKBANK**.
Details for configuring JWS is provided below:
JWS Signing algorithm RS256 JWS Output Format JWS JSON serialization Private key to be used by client for request payload signing Client’s Private Key that corresponds to the certificate shared with the bank for mutual SSL authentication that is available only with the client Public key used at RAKBANK for request payload verification Client’s Public Key shared with the bank for mutual SSL authentication Private key used at RAKBANK for response payload signing RAKBANK’s API Domain Private Key available only with the bank Public key to be used by client for response payload verification RAKBANK’s API Domain Public Key available with the client The JWS signed payload would typically have the below structure:
{
"payload":"BASE64URL(JWS Payload)",
"signatures":[
{"protected":"BASE64URL(UTF8(JWS Protected Header 1))",
"header":<non-integrity-protected header 1 contents>,
"signature":"BASE64URL(JWS Signature 1)"},
...
{"protected":"BASE64URL(UTF8(JWS Protected Header N))",
"header":<non-integrity-protected header N contents>,
"signature":"BASE64URL(JWS Signature N)"}
]
}Digital Encryption using JWE
JWE that stands for JSON Web Encryption, is commonly used for encrypting JSON Web Tokens (JWT). Clients are expected to encrypt the digitally signed JSON request payload before invoking a POST or PUT endpoint of an API, using JWE. For information on how to digitally sign the request payload, see Digital Signature using JWS. The JWE output format supported is JSON Serialization. The JSON response payload of an API will be digitally signed and encrypted at RAKBANK**.
Details for configuring JWE is provided below:
JWE Encryption algorithm (enc value) A256CBC-HS512 Key Encryption algorithm (alg value) RSA-OAEP-256 JWE Output Format JWE JSON serialization Public key to be used by client for request payload encryption RAKBANK’s API Domain Public Key available with the client Private key used at RAKBANK for request payload decryption RAKBANK’s API Domain Private Key available only with the bank Public key used at RAKBANK for response payload encryption Client’s Public Key shared with the bank for mutual SSL authentication Private key to be used by client for response payload decryption Client’s Private Key that corresponds to the certificate shared with the bank for mutual SSL authentication that is available only with the client The JWE encrypted payload would typically have the below structure:
{
"protected":"BASE64URL(UTF8(JWE Protected Header))",
"unprotected":"JWE Shared Unprotected Header"",
"recipients":[
{"header":JWE Per-Recipient Unprotected Header 1,
"encrypted_key":"BASE64URL(JWE Encrypted Key 1)"},
...
{"header":JWE Per-Recipient Unprotected Header 2,
"encrypted_key":"BASE64URL(JWE Encrypted Key N)"}
],
"aad":"BASE64URL(JWE AAD))",
"iv":"BASE64URL(JWE Initialization Vector)",
"ciphertext":"BASE64URL(JWE Ciphertext)",
"tag":"BASE64URL(JWE Authentication Tag)"
}Libraries for implementing JSON Object Signing and Encryption (JOSE) specifications for JWS & JWE are widely available for different programming languages. You can refer the below links to download the libraries suited for your application.
https://jwt.io/
https://openid.net/developers/jwt/
https://connect2id.com/products/nimbus-jose-jwtThe diagram below quickly explains the Digital Signature & Encryption requirement for invoking RAKBANK Open APIs.
The table below summarizes the Digital Signature & Encryption requirement for invoking RAKBANK’s Open APIs in UAT & Production environments
Digital Signature (JWS) & Encryption (JWE) of the Request at client side Client should do following steps to Digitally Sign & Encrypt the JSON message before sending it to RAKBANK’s Open API Platform:
- Client will digitally sign the JSON request with their private key.
- Encrypt the digitally signed message using RAKBANK’s public key.
Decryption (JWE) & Verification (JWS) at RAKBANK’s side Following steps will be done on RAKBANK’s Open API Platform to decrypt & verify the message:
- RAKBANK API platform will decrypt the message using its private key.
- Verify the signature using client’s public key.
Digital Signature (JWS) & Encryption (JWE) of the Response at RAKBANK’s side Following steps will be done on RAKBANK’s Open API Platform to sign & encrypt the response:
- API platform will sign the JSON response with its private key.
- Encrypt the signed message using client’s public key and send back to client.
Decryption (JWE) & Verification (JWS) of Response at Client’s side Client should do the following steps to decrypt & verify the response
- Upon receipt of the response, client has to decrypt using its private key.
- After decryption client has to verify the signature using RAKBANK’s public key.
** The OAuth token response of RAKBANK Customer Sign-in OAuth API 1.0.0 is the only case where the response payload is not digitally signed or encrypted.
API Keys
When you register an application, the application is assigned a unique client ID and client secret. These are known as API keys. You must use the client ID when you call an API that requires you to identify your application by using a client ID. In some cases, where OAuth 2.0 does not apply, both the API keys i.e. the client ID and the client secret will be expected to be passed by the client, in the HTTP header. For information on the OAuth 2.0 flows supported by the bank, see OAuth 2.0.
The Security section in the API docs of every API, provide the details of the security definitions that are applicable for the API, as shown in the below screenshot.
The client ID API key needs to be passed in the HTTP header as shown below in the sample cURL command for invoking the GET method of the Partner Beneficiary Management API.
OAuth2.0
OAuth 2.0 is the industry-standard protocol for authorization. OAuth2 is applicable for most of the RAKBANK Open APIs. The Security section in the API docs of every API, provide the details of the security definitions that are applicable for the API, as shown in the below screenshot.
Where OAuth is applicable, the supported OAuth API endpoints, grant types and scope applicable for the API would also be provided. The client will need to invoke one of the supported OAuth API endpoints and generate an access token. A valid access token should be then passed in the Authorization header as “Bearer {token}” while invoking the API, as shown below in the sample cURL command for invoking the GET method of the Partner Beneficiary Management API.
Depending on the type of client, the following OAuth APIs and grant types are supported. For information on client types supported by our Open APIs, see Who can use our APIs?
Type Of Client Public/ Confidential OAuth Grant Type OAuth API Name FinTechs & Third Party Apps Confidential Authorization Code RAKBANK Customer Sign-in OAuth API Partner Institutions Confidential Client Credential (also called oauth2 application) Partner Authentication API External Cloud Hosted RAKBank Apps Confidential Client Credential (also called oauth2 application) Internal Client Authentication API OAuth Authorization Code Grant Type
If you are interested in generating the OAuth token using this grant type, you will need to do the following:
- Register an application, to get a unique client ID and client secret.
- When registering the application, mention the callback URL of server where the Authorization code will be directed, in the Redirect URI text box.
- Subscribe to RAKBANK Customer Sign-in OAuth API
Authorization Request
To initiate the authentication flow, redirect the client to the /authorize endpoint with the required parameters in the query string.
Mandatory Query Parameters
Parameter name Description response_type “code” client_id client ID of the App scope The scope, as provided in the API docs of the API, that needs to be accessed using the access_token. Multiple scopes can be passed as a space separated list. account_id Account number entered by the user, encrypted using RAKBANK’s public key shared with the client. uuid Holds the uuid of the customer who is redirected to the /authorize endpoint. Optional Query Parameters
Parameter name Description state Randomly generated string used by the client to maintain state between the request and callback. redirect_url Needs to be sent only if multiple Redirect URIs were provided during the App registration. Sample Request
Sample Response
The diagram below shows the Authorization Request flow
Note: The Authorization code generated will be valid for a very short period and can be used only once to generate an Access Token and a Refresh Token
Access Token Request
Once the authorization code has been obtained, it can be exchanged for an access token by sending a POST request to the /token endpoint. This request needs to be authenticated using HTTP Basic Auth with your client_id as username and client_secret as password. The basic auth should be a base64 encoded string in the following format: "client_id:client_secret".
Mandatory Header Parameters
Parameter name Description Authorization Basic {basic64encoded value of string (client_id:client_secret)} Content-Type application/x-www-form-urlencoded Mandatory Body Parameters
Parameter name Description grant_type “authorization_code” code Authorization code Sample Request
Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThh”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "transfers account_transactions account_balances",
"refresh_token": "AAJk485lbQxSDtv88rd7_jYYkBJ232kVwPh0a1g7 ",
"refresh_token_expires_in": 2682000
}Note:
- The Access Token generated will be valid for 1 hour.
- Please ensure the access token is being re-used for subsequent API calls till its expiry time.
- If the access token has expired you will receive a 401 unauthorized error when invoking the actual API.
Using the Refresh Token
If you were provided with a refresh token you can use it to keep the connection alive by exchanging it for a new access and refresh token within it's lifetime.
To do this, send another request to the /token endpoint with 'grant_type=refresh_token'.
Mandatory Header Parameters
Parameter name Description Authorization Basic {basic64encoded value of string (client_id:client_secret)} Content-Type application/x-www-form-urlencoded Mandatory Body Parameters
Parameter name Description grant_type “refresh_token” refresh_token Refresh Token Sample Request
Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThhNjUtZTM0M2”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "transfers account_transactions account_balances",
"refresh_token": "AAJk485lbQxSDtv88rd7_jYYkBJ232kVwPh0a1g7Hz",
"refresh_token_expires_in": 2682000
}Note: The Refresh Token generated will be valid for 3 years and requires to be exchanged at least once in 6 months. The time out value may change as per Bank’s Information security policies.
About the OAuth Metadata
The Access Token & Refresh Token generated are unique for a combination of Customer UUID and Account Id (passed in the /authorize endpoint). These details of the customer are stored in the metadata within the OAuth tokens. When the access token is presented in the authorization header of an API, the API uses the metadata within the token to identify the customer and his account for which he authorized the request. The Account Id should be passed as masked values in the API request. For e.g. in the below screenshot taken from Account Transactions API, the parameter account_id is expected to be passed as a masked value in the path.
The masked Account Id needs to be passed in the request path as shown below in the sample cURL command for invoking the GET method of the Account Transactions API. For information on the masking logic to be followed, see Masking Logic.
Note:
- Please ensure the access token generated for a combination of Customer UUID and Account Id is being re-used for subsequent API calls ONLY meant for that combination of Customer UUID and Account Id.
- Please ensure the Refresh Token is always stored on the server, against the appropriate Customer UUID and Account Id, in encrypted format.
- RAK Bank will not be liable for any API calls which was sent with a mismatched access token i.e. an access token that was not created for the Customer UUID/Account ID on which the transaction was performed.
OAuth Client Credentials (application) Grant Type
If you are interested in generating the OAuth token using this grant type, you will need to do the following:
- Register an application, to get a unique client ID and client secret for your App
- Subscribe to Partner Authentication API if you are a developer from a partner institution
- Subscribe to Internal Client Authentication API if you are developer working on an external cloud hosted RAKBANK App
Access Token Request
Send a request to the /token endpoint with 'grant_type=client_credentials’. This request needs to be authenticated by passing both the client_id and client_secret in the HTTP header.
Mandatory Header Parameters
Parameter name Description X-IBM-Client-Id client_id X-IBM-Client-Secret client_secret Content-Type application/json MsgId Unique id for the request Mandatory Body Parameters
Parameter name Description grant_type “client_credentials” scope The scope, as provided in the API docs, of the API that needs to be accessed using the access_token. Multiple scopes can be passed as a space separated list. Optional Body Parameter
Parameter name Description oauth_metadata oauth_metadata object must be passed for specific scopes. Wherever applicable, the API docs will have the details. For more information, see About the OAuth Metadata. Sample Request
POST https://api.rakbank.ae/rb/api/v1/partner_auth/token
HTTP/1.1
Host: https://api.rakbank.ae
X-IBM-Client-Id: CLIENT_ID
X-IBM-Client-Secret: CLIENT_SECRET
Content-Type: application/json
Accept: application/json
MsgId: 23623864
{
"grant_type": "client_credentials",
"scope": "beneficiary_management send_money",
"oauth_metadata": {
"account_id":"1234567890123"
}
}Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThh”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "beneficiary_management send_money"
}Note:
- The JSON request sent to the /token endpoint should be digitally signed and encrypted by the client. The JSON response will be digitally signed and encrypted by RAKBANK. For information on digital signature and encryption, see Digital Signature using JWS & Digital Encryption using JWE.
- The Access Token generated will be valid for 1 hour. Please ensure the access token is being re-used for subsequent API calls for a particular user session rather than generating a new token before every API call.
About the OAuth Metadata
The details passed by the client in the oauth_metadata parameter, while invoking the /token endpoint, are stored in the metadata within the OAuth access token. Wherever applicable, the API docs will have the details of what needs to be passed in oauth_metadata while generating the token for that API. For e.g. the screenshot below taken from Partner Beneficiary Management API expects the client to pass either account_id or emirates_id in the oauth_metadata parameter.
When the generated access token is presented in the authorization header of an API, the API uses the metadata within the token to identify the Account Id or Emirates Id for which the token was authorized. The Account Id or Emirates Id should be passed as masked values in the API request. For e.g. in the below screenshot taken from Partner Beneficiary Management API, the parameter customer_id is expected to be passed as a masked value in the path. For information on the masking logic to be followed, see Masking Logic.
Note:
- Please ensure the access token generated for a specific account_id in the oauth_metada is being re-used for subsequent API calls ONLY meant for that account_id. For e.g. if account id 1234567890123 is passed in oauth_metada.account_id in the /token endpoint that returns access token tkn12345, then all subsequent API calls where access token tkn12345 is passed in Authorization header must be for operations on the account id 1234567890123 ONLY. This access token cannot be used for any other account.
- RAK Bank will not be liable for any API calls which was sent with a mismatched access token.
Masking Logic
The masking logic to be followed for the parameter is as mentioned below:
First 4 and last 3 characters to be unmasked. All characters in between to be masked by replacing with 'x'. For e.g.
Account Id 1234999999567 will be passed as 1234xxxxxx567
Emirates Id 7841999999999999567 will be passed as 7841xxxxxxxxxxxx567.The masked Account Id needs to be passed in the request path as shown below in the sample cURL command for invoking the POST method of the Partner Beneficiary Management API.
-
Sandbox Environment
The following list of API security policies apply to our Sandbox Environment
- API Key(s)
- OAuth2
API Keys
When you register an application, the application is assigned a unique client ID and client secret. These are known as API keys. You must use the client ID when you call an API that requires you to identify your application by using a client ID. In some cases, where OAuth 2.0 does not apply, both the API keys i.e. the client ID and the client secret will be expected to be passed by the client, in the HTTP header. For information on the OAuth 2.0 flows supported by the bank, see OAuth 2.0.
The Security section in the API docs of every API, provide the details of the security definitions that are applicable for the API, as shown in the below screenshot.
The client ID API key needs to be passed in the HTTP header as shown below in the sample cURL command for invoking the GET method of the Partner Beneficiary Management API.
OAuth 2.0
OAuth 2.0 is the industry-standard protocol for authorization. OAuth2 are applicable for most of the RAKBANK Open APIs. The Security section in the API docs of every API, provide the details of the security definitions that are applicable for the API, as shown in the below screenshot.
Where OAuth is applicable, the supported OAuth API endpoints, grant types and scope applicable for the API would also be provided. The client will need to invoke one of the supported OAuth API endpoints and generate an access token. A valid access token should be then passed in the Authorization header as “Bearer {token}” while invoking the API, as shown below in the sample cURL command for invoking the GET method of the Partner Beneficiary Management API.
Depending on the type of client, the following OAuth APIs and grant types are supported. For information on client types supported by our Open APIs, see Who can use our APIs?
Type Of Client Public/ Confidential OAuth Grant Type OAuth API Name FinTechs & Third Party Apps Confidential Authorization Code RAKBANK Customer Sign-in OAuth API Partner Institutions Confidential Client Credential (also called oauth2 application) Partner Authentication API External Cloud Hosted RAKBank Apps Confidential Client Credential (also called oauth2 application) Internal Client Authentication API OAuth Authorization Code Grant Type
If you are interested in generating the OAuth token using this grant type, you will need to do the following:
- Register an application, to get a unique client ID and client secret.
- When registering the application, mention the callback URL of server where the Authorization code will be directed, in the Redirect URI text box.
- Subscribe to RAKBANK Customer Sign-in OAuth API
Authorization Request
To initiate the authentication flow, redirect the client to the /authorize endpoint with the required parameters in the query string.
Mandatory Query Parameters
Parameter name Description response_type “code” client_id client ID of the App scope The scope, as provided in the API docs, of the API that needs to be accessed using the access_token. Multiple scopes can be passed as a space separated list. Optional Query Parameters
Parameter name Description state Randomly generated string used by the client to maintain state between the request and callback. redirect_url Needs to be sent only if multiple Redirect URIs were provided during the App registration. Sample Request
Sample Response
Note: The Authorization code generated will be valid for a very short period and can be used only once to generate an Access Token and a Refresh Token
Access Token Request
Once the authorization code has been obtained, it can be exchanged for an access token by sending a POST request to the /token endpoint. This request needs to be authenticated using HTTP Basic Auth with your client_id as username and client_secret as password. The basic auth should be a base64 encoded string in the following format: "client_id:client_secret".
Mandatory Header Parameter
Parameter name Description Authorization Basic {basic64encoded value of string (client_id:client_secret)} Content-Type application/x-www-form-urlencoded Mandatory Body Parameters
Parameter name Description grant_type “authorization_code” code Authorization code 
Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThh”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "transfers account_transactions account_balances",
"refresh_token": "AAJk485lbQxSDtv88rd7_jYYkBJ232kVwPh0a1g7 ",
"refresh_token_expires_in": 2682000
}Note:
- The Access Token generated will be valid for 1 hour.
- Please ensure the access token is being re-used for subsequent API calls till its expiry time.
- If the access token has expired you will receive a 401 unauthorized error when invoking the actual API.
Using the Refresh Token
If you were provided with a refresh token you can use it to keep the connection alive by exchanging it for a new access and refresh token within it's lifetime.
To do this, send another request to the /token endpoint with 'grant_type=refresh_token'.
Mandatory Header Parameter
Parameter name Description Authorization Basic {basic64encoded value of string (client_id:client_secret)} Content-Type application/x-www-form-urlencoded Mandatory Body Parameters
Parameter name Description grant_type “refresh_token” refresh_token Refresh Token Sample Request
Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThhNjUtZTM0M2”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "transfers account_transactions account_balances",
"refresh_token": "AAJk485lbQxSDtv88rd7_jYYkBJ232kVwPh0a1g7Hz",
"refresh_token_expires_in": 2682000
}OAuth Client Credentials Grant Type
If you are interested in generating the OAuth token using this grant type, you will need to do the following:
- Register an application, to get a unique client ID and client secret for your App
- Subscribe to Partner Authentication API if you are a developer from a partner institution
- Subscribe to Internal Client Authentication API if you are developer working on an external cloud hosted RAKBANK App
Access Token Request
Send a request to the /token endpoint with 'grant_type=client_credentials’. This request needs to be authenticated using HTTP Basic Auth with your client_id as username and client_secret as password. The basic auth should be a base64 encoded string in the following format: "client_id:client_secret".
Mandatory Header Parameters
Parameter name Description Authorization Basic {basic64encoded value of string (client_id:client_secret)} Content-Type application/x-www-form-urlencoded Mandatory Body Parameters
Parameter name Description grant_type “client_credentials” scope The scope, as provided in the API docs, of the API that needs to be accessed using the access_token.
Multiple scopes can be passed as a space separated list.Sample Request
Sample Response
{
"token_type": "bearer",
"access_token": "AAIkOGY4Yjc5NDUtZWVlNy00NTBjLThh”,
"expires_in": 3600,
"consented_on": 1562687596,
"scope": "beneficiary_management send_money"
}