---
updatedAt: 2026-11-12T11:23:52.000Z
agentTools:
  projectIndex: https://docs.developer.rabobank.com/payments/llms.txt
---

# API Workflow & Setup

This document describes the standard authorization flow. It explains how to request user consent, obtain access tokens, retrieve consent details, and refresh expired access tokens.

Use this flow for all Premium APIs that require OAuth 2.0 authorization.

For error scenarios, see Try it Out (Sandbox).

## Before you begin

Complete the following requirements before using the Authorization Services.

<Accordion title="Sandbox Requirements" icon="fa-info-circle">
  - Set up a [sandbox account](https://docs.developer.rabobank.com/platform/docs/getting-started#sandbox-account)
  - Set up [sandbox application and subscription](https://docs.developer.rabobank.com/platform/docs/account-and-organization#apps) to:
    - Any premium API
  - Set up your [Mutual TLS connection](https://docs.developer.rabobank.com/payments/docs/mutual-tls), you can find our example certificates for sandbox here.
  - Set up your [signing certificate](https://docs.developer.rabobank.com/payments/docs/validate-signing-requests), example certificates for sandbox here.
</Accordion>

<Accordion title="Production Requirements" icon="fa-info-circle">
  - Set up a production account. To get a production account, see [Go to Production](https://docs.developer.rabobank.com/payments/docs/go-to-production-authorization-services)
  - Set up [production application and subscription](https://docs.developer.rabobank.com/platform/docs/account-and-organization#apps) to:
    - Any premium API
  - Set up your [Mutual TLS connection](https://docs.developer.rabobank.com/payments/docs/mutual-tls) with your EV SSL certificate
  - Set up your [signing certificate](https://docs.developer.rabobank.com/payments/docs/validate-signing-requests)
</Accordion>

## Required Headers

Include the following headers where applicable.

| Name            | Description                                                                                                    | Format |
| :-------------- | :------------------------------------------------------------------------------------------------------------- | :----- |
| X-Request-ID    | Universally Unique Identifier (UUID) generated by your application. Required for the Consent Details endpoint. | UUID   |
| X-IBM-Client-ID | UUID generated by your application. Required for the Consent Details endpoint.                                 | UUID   |
| Authorization   | HTTP Basic Authentication using a Base64-encoded `client_id:client_secret`. Required for the token endpoint.   | String |

<Callout icon="📘" theme="info">
  The token endpoint uses request body parameters instead of headers. The authorization endpoint uses query parameters instead of headers.
</Callout>

## OAuth Authorization Flow Overview

![](https://files.readme.io/abdbcc919e6f57ec2f28abdd2c9199e5db134b4a3a1e6d7a6fec4fa539b9b36c-Authorization_flow.png)

## Step 1 - Request user consent

**Endpoint:**

[Authorization code and implicit grants](https://docs.developer.rabobank.com/payments/reference/getauthorize)<br />`GET /authorize`

**Purpose:** Request user consent and start the authorization flow.

**Required parameters:**

| Parameter      | Purpose                                                                                                              |
| :------------- | :------------------------------------------------------------------------------------------------------------------- |
| response\_type | Use `code` for the authorization code grant flow.                                                                    |
| scope          | Space-separated list of permissions requested from the user. Request multiple scopes by separating them with spaces. |
| client\_id     | Value of the `X-IBM-Client-ID` assigned to your application.                                                         |

**Optional parameters:**

| Parameter     | Purpose                                                                                                                           |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| state         | Maintain state between the request and callback.                                                                                  |
| redirect\_uri | Required when multiple redirect URIs are configured for your application. The value must exactly match a registered redirect URI. |

After the user grants consent, Rabobank redirects the user to your configured redirect URI with an authorization code.

<Callout icon="📘" theme="info">
  Consents remain valid until the user revokes them. Users can also revoke consent in Rabobank Business Banking.
</Callout>

<Callout icon="🚧" theme="warn">
  Do not embed the Rabobank authorization page in your application. Open it in the user's browser.
</Callout>

## Step 2 - Exchange the authorization code for a token pair

**Endpoint:**

[Request Access Tokens](https://oauth.rabobank.nl/openapi/oauth2-premium/token)<br />`POST /token`

**Purpose:** Exchange the authorization code for an access token and refresh token.

**Required headers:**

| Header        | Purpose                                                                     |
| :------------ | :-------------------------------------------------------------------------- |
| Authorization | HTTP Basic Authentication using a Base64-encoded `client_id:client_secret`. |

**Required body parameters:**

| Parameter   | Value                                                       |
| :---------- | :---------------------------------------------------------- |
| grant\_type | `authorization_code`                                        |
| code        | Authorization code received from the authorization endpoint |

**Optional body parameters:**

| Parameter     | Purpose                                                                                                                    |
| :------------ | :------------------------------------------------------------------------------------------------------------------------- |
| redirect\_uri | Required when the authorization request included a `redirect_uri`. The value must match the authorization request exactly. |

The response contains:

* `access_token`
* `refresh_token`
* `expires_in`
* `refresh_token_expires_in`
* `metadata`

The `metadata` field contains the `consentId`. Use this value with the Consent Details Service.

<Callout icon="📘" theme="info">
  The authorization code is valid for a single use. Exchange it immediately after receiving it.
</Callout>

## Step 3 - Access user account

**Purpose:** Access APIs on behalf of the user with the access token.

Include the access token in the Authorization header of every request:

```http
Authorization: Bearer ACCESS_TOKEN
```

Use the access token until it expires.

When the access token expires, continue with Step 4.

## Step 4 - Refresh the token pair

**Endpoint:**

[Request Access Tokens](https://oauth.rabobank.nl/openapi/oauth2-premium/token)<br />`POST /token`

**Purpose:** Exchange the refresh token for a new access token and refresh token.

**Required headers:**

| Header        | Purpose                                                                     |
| :------------ | :-------------------------------------------------------------------------- |
| Authorization | HTTP Basic Authentication using a Base64-encoded `client_id:client_secret`. |

**Required body parameters:**

| Parameter      | Value                             |
| :------------- | :-------------------------------- |
| grant\_type    | `refresh_token`                   |
| refresh\_token | Previously received refresh token |

The response returns:

* New `access_token`
* New `refresh_token`
* Expiry times of new tokens

<Callout icon="📘" theme="info">
  Refresh tokens are single-use. Store the new refresh token returned in each successful refresh response.
</Callout>

After refreshing the token pair, return to Step 3.

This process of using and refreshing tokens is called **token management**. Proper token management ensures uninterrupted access to protected resources.

![](https://files.readme.io/5e40647bd71e7908419a1f5d6d9be0d71ad99a2f05736e93b679352f966ebb48-Refresh_token_pair_flow.png)

## Optional next step - Retrieve consent details

**Endpoint:**

[Get consent details](https://api.rabobank.nl/openapi/oauth2-premium/v1/consents/\{consentId})<br />`GET /v1/consents/{consentId}`

**Purpose:** Retrieve details of an existing consent.

Use the `consentId` from the `metadata` field in the token response to retrieve:

* Consent status
* Consented scopes
* Associated accounts
* Account status
* Expiry information

**Required parameters:**

| Parameter | Purpose                                |
| :-------- | :------------------------------------- |
| consentId | Identifier of the consent to retrieve. |

Use this endpoint to verify that a consent is still active or to troubleshoot `CONSENT_INVALID` responses.

## Download API Specifications

* [Authorization Services](https://docs.developer.rabobank.com/payments/openapi/Access%20Authorization.json)
* [Consent Details Service](https://docs.developer.rabobank.com/payments/openapi/Premium%20Consent%20Details.json)