RBC APIs uses OAuth 2.0 Specification for authentication and authorization. The platform supports common OAuth 2.0 authorization scenarios including server-side apps, client-side apps as well as private apps for server-to-server interactions using service accounts. To enable safe and secure communications all apps must authorize against the RBC Authorization Server before being able to access any data or perform actions against the platform.

This guide provides an overview of the various OAuth 2.0 authorization scenarios that the RBC API supports.

Basic Steps

All the apps follow a common pattern when accessing RBC APIs using OAuth 2.0. The following represents the steps at a high level:

Credentials

The first step is to obtain the credentials needed for authorization. This step works differently for different use cases and the type of access. For examples, private apps would need to request access for client credentials (apiKey and secret) while a client application would not need any credentials instead relying on user authentication when obtaining an access token.

❗️

It is of utmost importance the the client credentials are stored securely and access to it is restricted. It is the responsibility of the clients to ensure security of the client credentials.

Access Token Generation

Any app that needs to access any data or perform an action using an API must obtain an access token that grants access to that API. A single access token can be used to access multiple APIs depending on the access that was granted. The access token contains a parameter called scope which represents the various operations that can be performed.

There are several ways to obtain an access token, and they vary based on the type of application. For example, a private app for server-to-server interactions may use an apiKey and secret. Some requests may require an authentication step with the authorization server before it sends the access token.

If successful, the response body contains data with the following structure:

{
    "token": "jwt", 
    "tokenExpiresAt": "2021-01-31T05:30:30Z",
    "tokenType": "Bearer"
}

API Calls

Once the app obtains an access token, it can make API calls by sending the token to the API in an HTTP Authorization request header using Bearer Authentication. Though bearer authentication supports sending access tokens using additional options like query-string parameters, it is not secure and is not supported in the platform.

Here is an simple example that demonstrates retrieving a transaction:

curl --location -g --request GET 'api-preview.platform.rbcpayments.com/api/transaction/{transactionID}' \
--header 'Authorization: Bearer {jwt}'

🚧

This assumes that the app has the authorization to this operation as well as the necessary privileges to the requested resource. For instance, a merchant will not be able to access transaction of a different merchant even if the id of the resource is known.

Service Accounts

RBC platform provides support for server-to-server interactions such as server side web applications or services which needs to interact with the RBC API. These scenarios typically doesn't have direct end-user interaction as the service account belongs to the app rather than the end-user and is frequently referred as two-legged OAuth or 2LO and implemented using Client Credentials Flow. The following shows the steps involved:

1. The client credentials for service accounts can be obtained by contacting our partnership growth team temporarily and should be available through the merchant portal shortly.

2. The access token can be generated by sending the client credentials using Basic Authentication. A detailed step by step is provided below:

3. Once the access token is obtained, API calls can be made.

Access Token

The access token returned by the RBC Authorization Server uses the JWT format. The token can be decoded using any compatible tool or online at jwt.io.