Authentication

📘

API access tokens - what's new

• Token secret shown once at creation - for security reasons, the secret is only visible when the token is first created. Make sure to securely store it on your device right away, before exiting the page.
• Permissions are now grouped by business area and API - the permission list mirrors the general structure of Permissions, making it easier to understand what level of access you're granting.
• Explicit permission visibility for API keys - all keys now clearly show which permissions are included with your API key.
• Smart checkbox states for advanced access tokens - checkboxes are automatically disabled for permissions your account doesn't have, so you can instantly see what states are available to you and why.

Getting started

The Mollie API offers four authentication methods:

• API keys: default API access for a specific payment profile.
• Advanced access tokens: advanced API access for organization-level data.
  Optional: can be scoped to a specific mode or profile.
• App access tokens (OAuth): access that allows you to make API requests on behalf of your connected customers.
• Basic Auth: Base64-encoded string using the OAuth client ID and client secret as basic access credentials. It is used to generate and revoke tokens.

We recommend using API keys to get started.

API keys

📘

The API keys and Access tokens pages have been merged into a singular API access tokens page that you can find in your Mollie Web App under Developers.

API keys are used to authenticate and authorize API requests made by your application or backend systems. They're like secure passwords that identify your application to different systems.

The first thing you need is a website profile. Then, once you create one, you can generate API keys for it: Live API key and a Test API key.

Use a Test API key when building and testing your integration. Once you are ready to start processing real payments, you can swap your Test key for a Live API key.

Under Developers > API access tokens you can choose whether you want to:

• Create a standard API key (and add a second API key for a profile)
• Build your own advanced access token (which can be scoped to a specific mode or profile)

Rotating API keys

Previously, we only supported a single API key-pair per profile. This limitation has been lifted, which makes proper API key rotation possible. You can now:

1. Create a second API key for a profile
2. Start using the second API key in your integration
3. Only then remove the old API key safely

⚠️

It’s very important to keep your API keys secure, so do not share them and regularly rotate them.
Do not use API keys for third party integrations, but use OAuth instead.

If one or both of your keys accidentally leak, you can always regenerate them in the Web App.

Advanced access tokens

Advanced access tokens are special types of credentials used to grant access to organization-level resources. These are typically used for for organization-level actions: managing multiple connected accounts or users, automating administrative tasks, or integrating enterprise-level systems, however, they can also be scoped to a specific profile or mode.

Only users with the Admin role can currently create tokens. So if you do not have access to tokens - please ask the Admin of your Organization or have your role updated to Admin.

App access tokens (OAuth)

With app access tokens, you can talk to the Mollie API on behalf of your users or proactively revoke authorizations. These are the tokens used to authenticate API requests on behalf of your users or connected businesses, communicate with the Mollie API on behalf of the user (with their consent), access the merchant’s account data, retrieve information, do things on behalf of your customers etc.

See the full example flow in our Implementing OAuth guide.

Basic Auth

Basic Authentication is an HTTP authentication scheme that sends credentials as a Base64-encoded string: Authorization: Basic <base64-encoded-username:password>.

In Mollie we use the client ID and client secret as basic access credentials:

"Basic " + toBase64(client_id + ":" + client_secret)

Basic Auth is used to generate and revoke tokens.

Comparison of authentication methods

For completeness’ sake, the following table compares the available authentication methods.