Rabobank's PSD2 and Premium APIs require authorization, we offer the following authorization APIs:

  • PSD2 - OAuth 2.0
  • Premium - Authorization services, which is an OAuth 2.0 implementation for premium APIs.

The difference between these APIs is the consent days:

  • PSD2 - Consent is valid for 90 days. (After October 5th, it will be valid for 180 days.)
  • Premium - Consent is valid indefinitely until revoked.

These APIs enable your application to communicate with Rabobank, on behalf of a user, while keeping their usernames, passwords, and other information private.

If an API requires access authorization, this is specified in the API reference as Type: OAuth2.

Example:

AuthServ

The Consent Details Service API provides information about user consent to third parties, if authorized by the end user.

Before you begin

Make sure you have a working Sandbox account in the Rabobank developer portal. Read Get Started to set up an account and register an Application.

  1. After your account set up is complete, configure the OAuth 2.0 redirect URI for your application.

    If you have more than one redirect URL listed in the developer portal, make sure to provide the same redirect URI (as provided during registration) in the redirect_uri query parameter during an Authorization call.

  2. Next, subscribe the API you want to use and the Authorization Services API to your application.

    A subscription to these APIs is only required if you want to use the Consent Details Service API.

This API provides the services needed to obtain tokens for OAuth 2.0 secured APIs, Endpoint:

OAuth authorization flow

Applications using APIs, which require access authorization should follow the OAuth authorization code flow. This flow gives your application access to the required resources, if approved by the user.

rabo_oauth_authorization_flow

Request Authorization

Your application identifies the permissions (known as scopes) it requires from the resource owner and requests authorization to access their private information.

Example:

A user wants to use your application for creating payment requests, but they don’t want to share their account balance with it. The scopes your application identifies and requests, enables:

  • Your application to request access to the needed API resources.
  • User to control the amount of access they grant to your application.

You should not embed Rabobank's authorization page in your application, doing this will result in a ban.

Your application redirects the user to the following path:

https://oauth.rabobank.nl/openapi/oauth2/authorize?response_type=code&scope=SCOPES&client_id=CLIENT_ID&state=SOME_IDENTIFIER

https://oauth.rabobank.nl/openapi/oauth2-premium/authorize?response_type=code&scope=SCOPES&client_id=CLIENT_ID&state=SOME_IDENTIFIER

The request contains the:

  • Parameters that identify your application.
  • Permissions the user grants to your application.
URI Parameter Required? Example Description
response_type* Yes response_type=code

This indicates the authorization grant flow.

Value = code. Other response types are currently not supported.

scope Yes scope="bai.accountinformation.read”

Scopes represent permissions to resources, which your application requests from the user. Your application can request multiple scopes using a space separated list.

client_id* Yes ab588acc-2ac4-446c-abdd-06c2ea8b097a

This ID uniquely identifies your registered application.

The client_id is registered at Rabobank developer portal.

state No ABC123def567

An opaque value to maintain state while the user is being redirected back and forth between your application and Rabobank.

The  state parameter should be used to prevent CSRF attacks.

redirect_uri No your.redirect.url

Required only if you have more than one redirect_uri in your application.

If you add multiple redirect_urls to your application in the portal, you should use this parameter to identify, which redirect_url should be used for a specific call.

State parameter

You can use the state parameter to maintain state during the authorization code flow and prevent Cross Site Request Forgery (CSRF) attacks.

Use a strong value to prevent malicious users from being able to manipulate the state parameter.

User side:

A window is displayed, asking the user to give their consent and grant access to your application.

PSD2

PSD2

Screens_PremiumOAuth

Premium

Login and consent

The user decides whether or not to grant the permissions to your application. After the user's decision, the Rabobank OAuth server redirects the user agent back to your application using the URL available in Application details in the Rabobank developer portal.

If the user approves the access request, a response is sent from the Rabobank OAuth server to your application's URL containing an authorization code and state parameter:

https://your.redirect.url?code=AUTHORIZATION_CODE&state=SOME_IDENTIFIER

For PSD2 - Their consent is valid for 90 days. (After October 5th, it will be valid for 180 days.)

For Premium - Their consent is valid indefinitely until revoked.

If an active consent already exists, a new active consent is created. The consent is not overwritten by the additional consent from the same user.

The user can choose to revoke their consent at any time. If they do this, it voids the access token and the refresh token. If the consent has been revoked or expired, your application receives a response with a 403 Forbidden status. You can gain access again by requesting authorization from the user.

You can use the Consent Details Service API to see the status of the consent and verify if it has been revoked.

If the user does not approve the request, then the response from the Rabobank OAuth server to your application's URL contains an ‘access_denied’ error message.

https://your.redirect.url?error=access_denied

If the user cancels before authorizing the request, then the response from the Rabobank OAuth server to your application's URL contains an ‘access_denied’ error message.

https://your.redirect.url?error=access_denied

In case of an approval, the API redirects the user to your application, together with an authorization code. Your application uses this authorization code to request an access token from the Rabobank API(s) you want to use.

The authorization code is valid for a short time and can only be used once. Your application should use the code immediately after receiving, it is not necessary to store this code.

Access Token

After your application server receives an authorization code, it can exchange it for an access token. This request is made by your application server directly to the Rabobank server.

The access token is valid for 60 minutes for PSD2 and 24 hrs for Premium. Your application must include the access token in any API request that requires authorization from the user.

Access tokens should be stored securely and should only be used on the server side. If your application doesn't require constant access, we recommend to not store the access token.

Access token

Your application requests an access token in exchange for the authorization code by making a POST request to one of the following endpoints:

  • PSD2 - /oauth2/token
  • Premium - /oauth2-premium/token
POST /oauth2/token Headers: Content-Type: application/x-www-form-urlencoded Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET) Body (x-www-form-urlencoded): grant_type: authorization_code code: AUTHORIZATION_CODE

POST /oauth2-premium/token Headers: Content-Type: application/x-www-form-urlencoded Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET) Body (x-www-form-urlencoded): grant_type: authorization_code code: AUTHORIZATION_CODE

This request is secured with Basic authentication using your application's:

  • Client ID as username
  • Client Secret as password

Example:

Client id - ab588acc-2ac4-446c-abdd-06c2ea8b097a 
Client secret - J6aA1fL8vJ6xV0iI5bX4nR4nA8pK7dG3cI0jK5mR6rN2qQ3pP0

Authorization: Basic YWI1ODhhY2MtMmFjNC00NDZjLWFiZGQtMDZjMmVhOGIwOTdhOko2YUExZkw4dko2eFYwaUk1Ylg0blI0bkE4cEs3ZEczY0kwaks1bVI2ck4ycVEzcFAw

The client secret should be stored securely and should only be used on the server side.

Parameter Example Description
grant_type authorization_code This states a method that an application can use to obtain an access token. There are several types of grants, which allow different types of access.
code 2aks1bVI2ck4ycVEzcFAwYUExZkw4dko2eFYwaUk1Ylg0blI0bkE 4cEs3ZEczY0kwYWI1OD hhY2MtMmFjNC00NDZjLWFiZGQtMDZ jMmVhOGIwOTdhOko The AUTHORIZATION_CODE your application received in the previous step.

In requests to Rabobank APIs secured with OAuth 2.0, you must add the access token in the Authorization header:

Authorization: Bearer ACCESS_TOKEN

If the token has expired or the consent has been revoked, your application receives a response with a 401 Unauthorized status.

Refresh token

If the access token expires you can obtain a new one by using the refresh token. Your application can use the refresh token to obtain a new access token if:

  • The user's consent has not been revoked, and
  • The refresh token has not expired.

rabo_oauth_refresh_flow

The refresh token is valid for 30 days but can only be used one time. It should be stored securely and should only be used on the server side.

When your application obtains a new access token, it also receives a new refresh token.

The expiry time for access tokens is known so your application should be able to predict when it needs to refresh a token.

You should receive information about the access token and refresh token expiry in the Token request response. It is recommended to use the expiration date as specified in the Token response in your application settings.

The table below describes other limitations:

Tokens

Expiration Times

Consent As per the requested scope
Authorization code 5 minutes
Access token

PSD2 - 1 hour

Premium - 24 hours

Refresh limit 4096 times
Refresh token 30 days

The expiration time(s) is not fixed, we do not recommend regarding these values as a fixed value in your settings.

Most Rabobank APIs have a rate limit, making multiple requests at once results in a failure. You should make the requests in multiple batches at a regular time interval.

We recommend your application refreshes the token before it expires, in order to prevent your application from making unsuccessful requests.

The lengths of the access token and the refresh token are not fixed, so you should not limit their size in your storage.

POST /oauth2/token Headers: Content-Type: application/x-www-form-urlencoded Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET) Body (x-www-form-urlencoded): grant_type: refresh_token refresh_token: REFRESH_TOKEN

POST /oauth2-premium/token Headers: Content-Type: application/x-www-form-urlencoded Authorization: Basic BASE64(CLIENT_ID + ":" + CLIENT_SECRET) Body (x-www-form-urlencoded): grant_type: refresh_token refresh_token: REFRESH_TOKEN
Parameter Example Description
grant_type refresh_token This states a method that an application can use to obtain an access token. There are several types of grants, which allow different types of access.
refresh_token tGzv3JOkF0XG5Qx2TlKWIA The REFRESH_TOKEN that your application received with the previous set of tokens.

Your application can use the new access token to make requests to Rabobank API(s).

Receive Tokens

The response contains an access token, a refresh token, their expiration times in seconds, and the timestamp of when the consent was given.

{ "token_type": "bearer", "access_token": ACCESS_TOKEN, "expires_in": 86400, "consented_on": 1507267950, "metadata": "a:consentId 123a1a2a-888c-4015-8099-f88b080d0bbb", "scope": SCOPES, "refresh_token": REFRESH_TOKEN, "refresh_token_expires_in": 2592000 }

Security Considerations

The client secret, access token, refresh token, and data that you have retrieved from Rabobank API(s) is sensitive. They need to be handled carefully, we recommend following the guidelines below:

Keep tokens and client secret server side

The client secret of your application, the access and refresh tokens should never be sent out to the user (or be available to them).

Any traffic that sends one of these items should be server to server communication.

Use HTTPS

You are required to handle the transport of codes and tokens so we recommend using HTTPS to prevent hackers.

Type of Communication Requirement
Server – server communication When connecting your servers to the Rabobank API server, the use of HTTPS is required. You should always check the validity of our Rabobank HTTPS certificate.
Client – server communication When your client connects to your server:
  • make use of HTTPS to prevent hacking e.g. using a rogue wifi access point. You should always check the certificate during the HTTPS handshake. It should be your certificate and it should be valid, this is also known as certificate pinning.
  • make use of HTTP Strict Transport Security (HSTS). This ensures that the client always uses HTTPS to the specified domain.

Redirect to the preferred browser of the user

The authorization page as mentioned in the OAuth authorization flow must be opened in the user's preferred browser. Rabobank users can only confirm that they are authenticating with the genuine Rabobank site if they have the tools provided by their browser, such as the URL bar and Transport Layer Security (TLS) certificate information.

Redirecting authorization in native applications

For native applications, our authorization page must be opened in the default browser. Rabobank users can only confirm that they are authenticating with the genuine Rabobank site if they have the tools provided by their browser, such as the URL bar and Transport Layer Security (TLS) certificate information.

Native applications can use custom URL schemes as redirect URIs, to redirect the user back from the browser to the application that is requesting permission.

Any attempt to embed Rabobank’s authorization page results in your application being permanently banned from using Rabobank APIs.

Use Stable OAuth 2.0 Client Libraries

We recommend using stable libraries for performing the OAuth 2.0 process, instead of implementing your own.

If we suspect that your application has been compromised or detect suspicious activity, your application could be permanently banned from using Rabobank APIs.

Keep your application and its environment secure

Your application should be protected against cross site scripting, SQL injection, and other OWASP top 10 vulnerabilities. This is to prevent the leakage of sensitive information.

We recommend you do security tests on your application and its environment at regular intervals and with every major change.

Storing sensitive information

Make sure that only your application is capable of saving any sensitive information. We recommend you encrypt any sensitive data, and limit the authorization of storage devices.

More information on OAuth 2.0

For more information on OAuth 2.0, see:

Troubleshooting common OAuth 2.0 related problems

See OAuth2 error and troubleshooting guide for information on common problems and solutions related the connection to the Rabobank OAuth 2.0 flow.