Mailchimp API Authentication: Methods & Security Best Practices

Authentication overview

Authentication for the Mailchimp API governs access to an account's marketing data and capabilities, such as managing audiences, campaigns, and automations. The API primarily supports two distinct authentication methods: API keys and OAuth 2.0. The choice between these methods depends on the nature of the application integrating with Mailchimp.

API keys are suitable for server-to-server integrations, internal tools, or scripts where a single application needs full access to a specific Mailchimp account. They are straightforward to implement and manage directly within the Mailchimp user interface.

OAuth 2.0 is designed for third-party applications that interact with multiple Mailchimp accounts or require user consent for specific data access. This method provides a more secure and flexible way to grant limited permissions without sharing account credentials directly, aligning with modern authorization standards for web applications as defined by the OAuth 2.0 framework.

Supported authentication methods

The Mailchimp API offers two primary methods for authentication, each designed for different integration scenarios:

• API Keys: A long, unique string of characters associated with a Mailchimp account. It grants full access to the account's data and operations, acting as a secret password.
• OAuth 2.0: An industry-standard protocol that allows users to grant third-party applications limited access to their Mailchimp account without exposing their login credentials. It involves a secure handshake process to obtain an access token.

Comparison of Authentication Methods

Getting your credentials

The process for obtaining authentication credentials varies based on the chosen method.

For API Keys

1. Log in to your Mailchimp account.
2. Navigate to your profile by clicking your profile name in the bottom left corner.
3. Select "Account & Billing" from the dropdown menu.
4. Click "Extras" and then "API keys".
5. Under "Your API Keys", you can view existing keys or click "Create A Key" to generate a new one.
6. Copy the generated API key. This key is sensitive and should be treated like a password.

Refer to the official Mailchimp API reference for detailed steps on managing API keys.

For OAuth 2.0

To use OAuth 2.0, you must register your application with Mailchimp to obtain a Client ID and Client Secret. These credentials identify your application to Mailchimp's authorization server.

1. Go to the Mailchimp Developer site.
2. Log in to your developer account.
3. Register a new application, providing details such as your application's name, description, and crucially, a valid Redirect URI (or multiple URIs). The Redirect URI is where Mailchimp will send the user back after they authorize your application.
4. Upon registration, Mailchimp will provide you with a Client ID and Client Secret. These are confidential and should be stored securely.
5. Implement the OAuth 2.0 authorization flow in your application. This typically involves:
   1. Directing the user to Mailchimp's authorization endpoint with your Client ID and Redirect URI.
   2. The user logs into Mailchimp and grants permission to your application for requested scopes (e.g., read:campaigns, write:audiences).
   3. Mailchimp redirects the user back to your Redirect URI with an authorization code.
   4. Your application exchanges this authorization code for an access token (and often a refresh token) by making a server-side request to Mailchimp's token endpoint, including your Client ID and Client Secret.
   5. Use the access token to make authenticated API requests. Access tokens have a limited lifespan and must be refreshed using the refresh token when they expire.

For a comprehensive guide on implementing the OAuth 2.0 flow, consult the Authorization Code Grant documentation, which is the recommended flow for web applications.

Authenticated request example

Once you have your credentials, you can make authenticated requests to the Mailchimp API. The method of including the credentials depends on whether you are using an API key or an OAuth 2.0 access token.

Using an API Key

API keys are passed via HTTP Basic Authentication. The username is any string (often 'anystring' or 'apikey'), and the password is your Mailchimp API key. Alternatively, some client libraries abstract this, allowing you to pass the key directly.

Example using curl with Basic Authentication:

curl --request GET \
  --url "https://<dc>.api.mailchimp.com/3.0/lists" \
  --user "anystring:YOUR_API_KEY"

Replace <dc> with your data center (e.g., us1, eu1), which is typically part of your API key (e.g., YOUR_API_KEY-us1). The part after the hyphen is your data center.

Using an OAuth 2.0 Access Token

OAuth 2.0 access tokens are passed in the Authorization header using the Bearer scheme.

Example using curl with a Bearer token:

curl --request GET \
  --url "https://<api_root>/3.0/lists" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

The <api_root> for OAuth integrations is dynamically provided during the token exchange or can be derived from the instance URL returned by Mailchimp. This typically follows the structure <dc>.api.mailchimp.com, where <dc> is the data center.

Security best practices

Adhering to security best practices is crucial to protect your Mailchimp account and customer data when integrating with the API.

• Keep API Keys Confidential: Never hardcode API keys directly into client-side code (e.g., JavaScript). Store them as environment variables or in a secure configuration management system on your server. Avoid committing API keys to version control systems like Git.
• Use OAuth 2.0 for User-Facing Applications: For applications that users interact with directly or that access multiple Mailchimp accounts, always use OAuth 2.0. This prevents the need for users to share their Mailchimp credentials with your application and provides granular control over permissions.
• Limit API Key Permissions (if available): While Mailchimp API keys generally grant full access, if an API offers scoped keys, generate keys with the minimum necessary permissions. This reduces the blast radius if a key is compromised.
• Securely Store Refresh Tokens: If using OAuth 2.0, refresh tokens should be stored securely on your server, encrypted at rest, and accessed only by authorized server-side processes. They should never be exposed client-side.
• Rotate Credentials Regularly: Periodically generate new API keys and revoke old ones. For OAuth, ensure your refresh token strategy accounts for potential revocation or expiration, prompting users to re-authorize if necessary.
• Validate Redirect URIs: For OAuth 2.0, use strict validation for your registered Redirect URIs. Only allow HTTPS URIs to prevent interception of authorization codes.
• Implement HTTPS: All communication with the Mailchimp API should occur over HTTPS. This encrypts data in transit, protecting credentials and sensitive information from eavesdropping. Mailchimp enforces HTTPS for all API endpoints. The Cloudflare guide on HTTPS provides more details on its importance.
• Monitor API Usage: Regularly review your Mailchimp account's API usage logs for any unusual activity that might indicate unauthorized access.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could aid an attacker in identifying vulnerabilities.