Untangling the bunq OAuth and other account authentication methods: Which to use in your app?

Before bunq introduced the support of OAuth in July 2018, you could connect bunq accounts to your applications in two ways: by using the Connect feature or requesting the bunq user’s API key. Unless you are planning to integrate with your work mates only, we strongly recommend to opt for using OAuth.

Let’s see why OAuth is the best choice for building applications with the bunq API and puzzle out how (not) to use it.

What to use and when

API key

Since an API key grants full access to an account, it’s best suited for private use. API key based account authorization might have been a common thing but is slowly deprecating as the digital security standards evolve.

Perfect for: personal use.
Example: building graphs in Google Sheets for fun.

Connect

bunq Connect enables a bunq user to provide a (trusted) party with either full or restricted access to a monetary account, not the whole user account.

Full access entails making payments and seeing the entire transaction history. Limited access means the account owner will approve every payment initiated by the trusted party.

Another distinction is that a third party cannot request to connect a bunq user account. A Connect can only be initiated by a bunq account owner.

Perfect for: company use.
Example: sharing your business account with your bookkeeper

OAuth

Connecting a bunq account to a third party application via OAuth is both initiated and eventually approved by a bunq account owner. A third party is granted a scope of permissions. They can fulfil these permissions via a token that only works for this bunq account + application connection and identifies both parties.

Perfect for: business use.
Examples:

• integrating your business software with bunq.
• building an application.

Will anything change when PSD2 comes into force?

The OAuth flow will not change. We will introduce role based permission scopes, which will work with the PSD2-compliant bunq API.

As a PSD2 service provider that has an eIDAS signature, you will be able to perform either or both of the following roles:

• Payment Initiation Service Provider (PISP)
• Account Information Service Provider (AISP)

These role permissions are available for testing in the bunq sandbox.

Some bunq OAuth FAQs answered

What information can I access via OAuth?

• retrieve information on monetary accounts
• read payments
• get and create draft payments
• transfer money between the monetary accounts of the same user
• assign monetary accounts to cards
• retrieve request inquiries and request responses

What is the expiry time of the access token?

You define it when configuring the application logout time. By default, it is one week. If you send a request 30 seconds before the session expires, the session extends by your default logout time. However, the maximum time by which it can extend is 5 minutes.

How to make calls to the API using the OAuth token?

Just use the OAuth Token (access_token) as a normal bunq API key.

How to get the real user ID from session-server after OAuth?

Session-server does not return the customer ID. You can use the aliases of the monetary accounts like phone_number or email.

Can I get a home address via OAuth?

Home address is sensitive information, so no.

Is it possible to add a callback URL for card transactions with OAuth authentication?

No.

Bottom Line

Unless you think reintegration is an exciting thing to do, OAuth is the best authentication method to use when building apps with the bunq API. At least for the following reasons:

• Using API key based authentication or Connect does not conform to the PSD2 standard.
• OAuth is the only bunq authentication method allied to Strong Customer Authentication.

Building an app via the bunq API?

Tell us about your project in the comments below! We are always excited to hear from fellow bunqers that love our API as much as we do!