OAuth 2

OAuth 2 lets your application access Marketing API data on behalf of another Mailchimp user, without ever handling their credentials. It’s how third-party integrations work; Zapier, Slack, and Shopify all authenticate this way. It’s also a requirement for listing an integration in the Mailchimp Marketplace.

This page covers how the flow works. To implement it, see Set up an OAuth app.

The flow

Mailchimp implements the standard authorization code flow. Workflows differ between providers in small ways, so here’s Mailchimp’s:

1. Your application redirects the user to Mailchimp’s OAuth page, where they log in and authorize your application.
2. Mailchimp redirects the user back to your redirect_uri with a query string parameter named code.
3. Your server exchanges that code for an access token, in a request that also carries your client_secret. This step happens server-to-server, so the secret is never exposed to the browser.

You persist one value per user: the access token.

Tokens don’t expire

Mailchimp access tokens have no expiry, so there is no refresh_token and nothing to rotate on a schedule. A token stays valid until the user revokes your application’s access to their account, or until that user is removed from the account.

So a token that stops working means the user revoked your access. Retrying won’t help; send them back through the authorization flow instead.

The obligation runs both ways: when a user disconnects or uninstalls your application, delete the access token you stored for them, along with any syncing configuration tied to that connection. Don’t keep credentials for a connection the user has ended.

Your application’s credentials

Registering an application gives you two values:

• client_id identifies your application. It appears in the URL you redirect users to, so it isn’t secret.
• client_secret authenticates your application during the code exchange. It is secret, it’s shown only once at registration, and it can be rotated if exposed.