OAuth 2.0 is a protocol that will let your app connect to bunq users in a safe and easy way. Please be aware that if you will gain access to account information of other bunq users or initiate a payment for them, you may require a PSD2 permit.

What can my apps do with OAuth?

The permissions OAuth allows are the following:

  • read and create Monetary Accounts;

  • read Payments & Transactions;

  • create Payments between Monetary Accounts of the same user;

  • create Draft-Payments (the user will need to approve the payment using the bunq app);

  • assign a Monetary account to a Card;

  • read, create and manage Cards;

  • read and create Request-Inquiries

  • read Request-Responses.

Get started with OAuth

Follow these steps to get started with OAuth:

  1. Register an OAuth Client in the bunq app. You can find the OAuth menu by going Profile → Security & Settings → Developers → OAuth.

  2. Add one or more redirect URLs.

  3. Get your Client ID and Client Secret from the bunq app.

  4. Redirect your users to the OAuth authorization URL as described here.

  5. If the user accepts the authorization request, they will be redirected to the previously specified redirect_uri with an authorization Code parameter.

  6. Use the token endpoint to exchange the authorization Code for an Access Token.

  7. Use the Access Token as a normal API Key. Open a session or use our SDKs to get started.

Authorization Request

Your web or mobile app must redirect users https://oauth.bunq.com/auth using the following parameters:

  • response_type - bunq supports the authorization code grant. Provide code as a parameter (required);

  • client_id - your Client ID that you can get from the bunq app (required);

  • redirect_uri - the URL you wish the user to be redirected to after the authorization is complete (required);

  • state - a unique string to be passed back upon completion (optional).

Usehttps://oauth.sandbox.bunq.com/authin the sandbox environment.

Authorization request example:


Authorization request response example:


Token Exchange

If the authorization request is accepted by the user, you get the authorization Code. Exchange it for an Access Token.

Make a POST call to https://api.oauth.bunq.com/v1/token . Pass the following parameters as GET variables:

  • grant_type - the grant type used, use authorization_code for now (required)

  • code - the authorization Code you received after the authorization request was accepted (required)

  • redirect_uri - the same redirect URL you used with the authorization request (required)

  • client_id - your Client ID (required)

  • client_secret - your Client Secret (required)

Usehttps://api-oauth.sandbox.bunq.com/v1/tokenin the sandbox environment.

Token request example:


The request only contains URL parameters.

Example of a successful response:

"access_token": "8baec0ac1aafca3345d5b811042feecfe0272514c5d09a69b5fbc84cb1c06029",
"token_type": "bearer",
"state": "594f5548-6dfb-4b02-8620-08e03a9469e6"

Example of an error response:

"error": "invalid_grant",
"error_description": "The authorization code is invalid or expired."

What's next?

The access_token you've received can be used as a normal API key. Use it to create an authorized session with the user account.

When connecting to a bunq user's account using OAuth, you create a new user that access_token is associated with. This user has an ID. The bunq API expects you to use this ID as the user ID instead of the primary ID of the user that you connected with via OAuth.

When calling GET /user/{userID},you will expect to get UserPerson or UserCompany. Instead, you will get the UserApiKey object, which contains references to both the user that requested access (you) and the user that granted access (the bunq user account that you connected to).

Using the Connect button

Ready to connect to bunq users to your application? Do it with a Connect to bunq button. Feel free to use our style guide and prebuilt design assets.