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

To initiate authorization into the bunq user accounts, you need to create an OAuth Client and register at least 1 redirect URL for it.

The list of steps below will help you to get started:

1. Register an OAuth Client by creating an app in bunq Developer.

2. Add one or more redirect URLs.

3. Get your client_id and secret from your app information tab in bunq Developer.

4. Redirect your users to the OAuth authorization request URL.

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).

Authorization request example:

https://oauth.bunq.com/auth?response_type=code
&client_id=1cc540b6e7a4fa3a862620d0751771500ed453b0bef89cd60e36b7db6260f813
&redirect_uri=https://www.bunq.com
&state=594f5548-6dfb-4b02-8620-08e03a9469e6

Authorization request response example:

https://www.bunq.com/?code=7d272be434a75933f40c13d56aef6c31496005b653074f7d6ac57029d9995d30
&state=594f5548-6dfb-4b02-8620-08e03a9469e6

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)

Token request example:

https://api.oauth.bunq.com/v1/token?grant_type=authorization_code
&code=7d272be434a75933f40c13d56aef6c31496005b653074f7d6ac57029d9995d30
&redirect_uri=https://www.bunq.com/
&client_id=1cc540b6e7a4fa3a862620d0751771500ed453b0bef89cd60e36b7db6260f813
&client_secret=184f969765f6f74f53bf563ae3e9f891aec9179157601d25221d57f2f1151fd5

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."
}

User ID vs item IDs

When connecting to a bunq user's account using OAuth, you create a new user (userApiKey) that has its own id and access_token . When sending a request on behalf of a user connected to your app via OAuth, use the id of userApiKey as userId and the item ids of the bunq user (grantedByUser).

Example of a successful request URL:

https://api.bunq.com/user/{userApiKey's userId}/monetary-account/{grantedByUser's monetary-accountId}/payment

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.

• ​Style guide​

• ​Connect button assets​