Adyen Authentication: API Security & Credential Management

Authentication overview

Adyen employs various authentication mechanisms to secure API interactions, ensuring that only legitimate requests from authorized merchants are processed. The specific method depends on the API endpoint being accessed and the nature of the integration (server-side vs. client-side). These methods are designed to protect sensitive payment data and maintain compliance with industry standards like PCI DSS Level 1.

For most server-to-server API calls, Adyen relies on API keys for identification and authorization, often combined with HMAC signatures for message integrity. Client-side integrations, such as those involving the Adyen Web Drop-in or Components, utilize a Client Key and typically involve server-side calls for sensitive operations, where an API key is again used. Understanding the correct authentication flow for each API is critical for a secure and functional integration.

Adyen's authentication strategy aims to prevent unauthorized access, data tampering, and replay attacks, aligning with general API security principles such as those outlined by the OAuth 2.0 Bearer Token usage, though Adyen primarily uses proprietary API keys rather than OAuth for direct API access.

Supported authentication methods

Adyen supports several authentication methods, each suited for different integration scenarios:

API Key: This is the most common method for authenticating server-side requests. An API key is a unique string generated in your Adyen Customer Area. It must be sent in the X-Api-Key header for every API request. Each key can be configured with specific roles and permissions to adhere to the principle of least privilege.

HMAC Signature: HMAC (Hash-based Message Authentication Code) signatures are crucial for securing webhook notifications. When Adyen sends a notification to your endpoint, it includes an hmacSignature. You must verify this signature using a shared secret key (HMAC key) stored securely on your server. This process confirms that the notification is legitimate and hasn't been altered during transit.

Client Key: The Client Key is used in client-side integrations to initialize Adyen's frontend products like the Web Drop-in. It is publicly exposed in your web application and only grants access to non-sensitive client-side operations. Any sensitive actions, such as initiating a payment, still require a server-side call authenticated with an API key.

Getting your credentials

All necessary authentication credentials for Adyen integrations are managed within your Adyen Customer Area. Here's a breakdown of how to obtain them:

1. API Key:
   • Log in to your Adyen Customer Area.
   • Navigate to Developers > API credentials.
   • Select an existing API credential or create a new one.
   • Under Authentication, you will find the API Key. You can generate a new key if needed.
   • Ensure the API credential has the necessary roles (e.g., Checkout webservice role, Payouts webservice role) assigned for the APIs you intend to use.
2. HMAC Key (Webhook Secret):
   • In your Adyen Customer Area, go to Developers > Webhooks.
   • Select the webhook endpoint you want to configure or create a new one.
   • Under Security, you will find the HMAC Key. Copy this key and store it securely on your server. This key is sensitive and should not be publicly exposed.
3. Client Key:
   • Access your Adyen Customer Area.
   • Go to Developers > API credentials.
   • Select the API credential you are using for client-side integration.
   • The Client Key is displayed under Authentication. This key is designed for public use in your frontend application.

It is recommended to create separate API credentials for different applications or environments (e.g., development, testing, production) to enhance security and simplify management. Always store API keys and HMAC keys securely, preferably in environment variables or a secrets management service, and never hardcode them directly into your application code or expose them in client-side code.

Authenticated request example

Here's an example of an authenticated request using an API key for a server-side call to the Adyen Payments API. This example uses curl, but the principle applies to any programming language or HTTP client.

This request initiates a payment using the /payments endpoint:

curl -X POST \
  https://checkout-test.adyen.com/v69/payments \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{
    "amount": {
      "currency": "EUR",
      "value": 1000
    },
    "reference": "Your Order Number",
    "paymentMethod": {
      "type": "scheme",
      "number": "424242...",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvc": "123"
    },
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "returnUrl": "https://your-company.com/checkout/redirect"
  }'

In this example:

• YOUR_API_KEY must be replaced with your actual API key obtained from the Adyen Customer Area.
• The X-Api-Key header is crucial for authenticating the request.
• The request body contains the payment details, including amount, currency, reference, payment method details, and your merchant account.
• The endpoint URL (https://checkout-test.adyen.com/v69/payments) points to the test environment of the Payments API. For production, you would use a live endpoint URL.

Security best practices

Adhering to security best practices is paramount when integrating with Adyen to protect sensitive payment data and maintain compliance:

• Secure API Key Storage: Never hardcode API keys directly into your source code. Store them in environment variables, a secure configuration management system, or a secrets manager (e.g., Google Cloud Secret Manager, AWS Secrets Manager, Azure Key Vault). Restrict access to these keys.
• Principle of Least Privilege: Create separate API credentials for different purposes and grant them only the minimum necessary permissions. For example, a key used solely for processing payments should not have access to manage users or retrieve sensitive reports. Regularly review and update credential permissions.
• Use HTTPS/TLS: All communication with Adyen's APIs must occur over HTTPS (TLS). This encrypts data in transit, preventing eavesdropping and tampering. Adyen enforces HTTPS for all API endpoints.
• HMAC Signature Verification for Webhooks: Always verify the HMAC signature for every webhook notification received from Adyen. This ensures the notification's authenticity and integrity, preventing malicious actors from injecting fake or altered notifications into your system.
• Rotate Credentials Regularly: Implement a policy for regularly rotating your API keys and HMAC keys. This minimizes the risk associated with a compromised key. Adyen's Customer Area allows you to generate new keys and deactivate old ones.
• Monitor API Usage: Keep an eye on your API logs and usage patterns. Unusual activity could indicate a security breach or misconfiguration. Adyen provides tools within the Customer Area for monitoring API calls.
• Error Handling: Implement robust error handling without exposing sensitive information in error messages. Generic error messages are preferred for public-facing applications.
• PCI DSS Compliance: Adyen is PCI DSS Level 1 certified. While Adyen handles much of the PCI burden, your integration must still adhere to relevant PCI DSS requirements, especially concerning how you handle, store, or transmit cardholder data. Using Adyen's client-side encryption or Drop-in/Components helps minimize your PCI scope.
• Environment Separation: Use distinct sets of API keys and HMAC keys for your development, staging, and production environments. This prevents accidental changes to live systems and limits the impact of a security incident in a non-production environment.