Mollie Authentication: API Keys and Security Best Practices

Authentication overview

Mollie provides mechanisms to secure API access, ensuring that only authorized applications can interact with its payment processing services. The primary method for direct integrations is API key authentication, suitable for server-to-server communication where your backend system directly calls the Mollie API. This method involves generating unique keys from the Mollie Dashboard that grant specific permissions to perform actions such as creating payments, managing refunds, or retrieving transaction data.

For scenarios involving third-party applications or platforms (known as Mollie Connect applications), Mollie implements OAuth 2.0. This standard protocol allows users to grant specific permissions to an application without exposing their Mollie account credentials directly to that application. Instead, the application receives an access token, which it uses to make API requests on behalf of the user. This approach enhances security and user control, aligning with modern API security practices for delegated authorization, as detailed in the OAuth 2.0 specification.

Developers integrating with Mollie should choose the authentication method that best fits their application's architecture and security requirements. Proper handling and storage of credentials are paramount to prevent unauthorized access and maintain the integrity of payment operations. Mollie's documentation provides specific guidelines for each authentication method, including setup instructions and best practices for secure implementation, which are critical for maintaining PCI DSS compliance.

Supported authentication methods

Mollie supports two distinct authentication methods to cater to different integration types and security needs:

API Key Authentication

API keys are unique identifiers that grant access to your Mollie account's API. They are used for direct server-to-server communication. When you make a request to the Mollie API, you include your API key in the HTTP Authorization header. Mollie distinguishes between two types of API keys:

• Test API Keys: These keys are used in the Mollie test environment and allow you to simulate payments without actual financial transactions. They are ideal for development and debugging purposes.
• Live API Keys: These keys are used in the production environment and enable real financial transactions. They must be kept strictly confidential.

API keys typically provide broad access to your account's functionalities, depending on the permissions granted when the key is generated. It is crucial to manage these keys securely, rotating them periodically and restricting their scope where possible.

OAuth 2.0 (Mollie Connect)

OAuth 2.0 is an authorization framework designed for delegated access, primarily used for Mollie Connect applications. These are third-party applications or platforms that need to interact with a user's Mollie account on their behalf. Instead of sharing their Mollie credentials, users authorize the Connect application to access specific resources (e.g., create payments, view transactions) through a consent screen.

The OAuth 2.0 flow involves several steps:

1. The Connect application redirects the user to Mollie's authorization server.
2. The user logs into Mollie (if not already logged in) and grants permission to the application.
3. Mollie redirects the user back to the Connect application with an authorization code.
4. The Connect application exchanges the authorization code for an access token and optionally a refresh token.
5. The access token is then used to make API requests on behalf of the user.

OAuth 2.0 is particularly suitable for platforms that integrate with multiple Mollie merchants, providing a secure and scalable way to manage permissions without direct credential handling. The Mollie Connect OAuth 2.0 guide provides comprehensive details on implementation.

The following table summarizes Mollie's authentication methods:

Getting your credentials

To integrate with Mollie, you will need to obtain the appropriate credentials from your Mollie Dashboard.

API Keys

1. Log in to your Mollie Dashboard: Access your account at Mollie's official website.
2. Navigate to API Keys: In the dashboard, go to "Developers" > "API keys".
3. Generate Keys: You will see both your 'Live API key' and 'Test API key'. If you need to generate a new key or revoke an existing one, options are available on this page.
4. Copy Keys: Copy the relevant key (test for development, live for production). Be extremely careful with your live API key; treat it like a password.

Mollie API keys typically start with sk_live_ for live keys and sk_test_ for test keys. The full API key should be kept confidential and never exposed in client-side code or public repositories.

OAuth 2.0 Credentials for Mollie Connect

If you are building a Mollie Connect application, you will need a Client ID and Client Secret:

1. Register your application: In the Mollie Dashboard, go to "Developers" > "Mollie Connect".
2. Create a new application: Provide details such as your application's name, redirect URLs, and logo. Mollie will review and approve your application.
3. Obtain Client ID and Secret: Once your application is registered and approved, Mollie will provide you with a unique Client ID and Client Secret. These are essential for initiating the OAuth 2.0 flow.
4. Configure Redirect URLs: Ensure your registered redirect URLs accurately reflect where Mollie should send users back after authorization. These must be HTTPS URLs for security.

The Client Secret, like API keys, must be kept confidential and handled securely within your application's backend. Public clients (e.g., mobile apps) may use different flows like Proof Key for Code Exchange (PKCE) to enhance security without requiring a client secret, as recommended by the RFC 7636 (PKCE) specification.

Authenticated request example

When using API key authentication, you include your API key in the Authorization header of your HTTP requests. The key should be prefixed with Bearer.

Here's an example using curl to retrieve a list of payments:

curl -X GET \
  https://api.mollie.com/v2/payments \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Replace sk_live_YOUR_API_KEY with your actual live or test API key. This example demonstrates a basic GET request. For POST, PUT, or DELETE requests, you would typically include a JSON request body.

Mollie also provides official SDKs in several languages (PHP, Node.js, Ruby, Python, Java, ASP.NET) that abstract away the raw HTTP requests and handle authentication details for you. For instance, using the Node.js SDK:

const { createMollieClient } = require('@mollie/api-client');

const mollieClient = createMollieClient({
  apiKey: 'sk_test_YOUR_API_KEY' // Use your test or live API key
});

mollieClient.payments.all() // Fetches all payments
  .then(payments => {
    console.log(payments);
  })
  .catch(error => {
    console.error('Error fetching payments:', error);
  });

This Node.js example initializes the Mollie client with your API key, which is then automatically used for subsequent API calls. The Mollie API reference for listing payments provides further details and code examples across different languages.

Security best practices

Implementing strong security practices is critical when integrating with any payment gateway API. For Mollie authentication, consider the following recommendations:

• Protect API Keys and Client Secrets:
  • Never hardcode credentials: Do not embed API keys or client secrets directly into your source code.
  • Use environment variables: Store credentials in environment variables (e.g., MOLLIE_API_KEY) or configuration files that are not committed to version control.
  • Secrets management services: For production environments, use dedicated secrets management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) to store and retrieve sensitive credentials securely.
  • Restrict access: Limit access to these credentials only to the necessary personnel and systems.
• Use HTTPS for all communications: All interactions with the Mollie API should occur over HTTPS to ensure data encryption in transit. Mollie's API endpoints automatically enforce HTTPS.
• Implement IP whitelisting: If supported by your infrastructure, restrict API access to a predefined list of IP addresses that your servers use. This adds an extra layer of security by blocking requests from unknown locations.
• Regularly rotate API Keys: Periodically generate new API keys and revoke old ones. This minimizes the risk associated with a compromised key. The frequency depends on your organization's security policy.
• Principle of Least Privilege: Grant only the necessary permissions to your API keys or OAuth 2.0 tokens. For instance, if an application only needs to create payments, avoid giving it permissions to manage refunds or access sensitive customer data.
• Secure Webhooks: If you use Mollie webhooks for asynchronous event notifications, ensure your webhook endpoint is secured. Validate incoming webhook requests by verifying Mollie's signature using the X-Mollie-Signature header. This prevents spoofed requests and ensures data integrity. Mollie's webhook signature verification guide provides implementation details.
• Error Handling and Logging: Implement robust error handling to catch and log authentication failures. This can help identify potential security incidents. However, be cautious not to log sensitive credential information in error messages.
• Stay Updated: Keep your Mollie SDKs and any related libraries up to date. Updates often include security patches and improvements.
• Compliance: Adhere to relevant compliance standards like PCI DSS. Mollie is PCI DSS Level 1 certified, but your integration must also follow best practices to maintain a secure environment.