How to Use OAuth2

For developers integrating platforms that require clients to access Mailchimp’s servers, we recommend using OAuth2 for authorization. OAuth2 is a secure option that allows third-party applications to access a server without passing user credentials or API keys.

Before You Start

• The Mailchimp servers implement v10 of the OAuth2 specification and supports Web Server Flow.
• On the server side, OAuth2 is pure HTTPS, so we recommend using HTTPS for your redirect_uri.
• Tokens do not expire, so you do not need to use refresh_token.

Register Your Application

When you are ready to begin, register your application with Mailchimp following these steps:

1. In your Mailchimp account, navigate to the Account page.
2. In the drop-down menu, select Extras, and then API Keys.
3. Under the Developing an App? heading, click Register and Manage Your Apps.
4. Click Register an App.
5. In the appropriate fields, enter your application information.
6. Click Create.

After the registration is successful, an Application created message displays along with more information at the end of your form, including the Client_ID and Client Secret. Do not share the Client_ID and Client Secret.

On this screen, you do not need to save or change the information. Click Update or Cancel to go back to the Registered Apps page, or close the window.

Endpoints

OAuth2 exposes the following:

Flow

1. To start your application’s connection to Mailchimp, send the user to the authorize_uri.
2. The user enters their username and password to approve your application. “Remember Me” cookies are not permitted here.
3. After the user authorizes your application, the Mailchimp server redirects to the redirect_uri, along with a code you can exchange for an access_token. The code is valid for 30 seconds.
4. Your application should then make an out-of-band request to the access_token_uri using the code our server provided.
5. The Mailchimp server returns an access_token, which completes the official OAuth2 flow.
6. To complete the Mailchimp flow, make another RESTful request using an OAuth2 client to the metadata_uri.

Configuration Information

User-Specific Configuration

Mailchimp Standard OAuth2 Configuration

Mailchimp Custom Configuration

Example Request-Response Flow

Your application begins the authorization process by redirecting the user to the authorize_uri. This is a GET request, and response_type=code, your client_id, and the url-encoded redirect_uri are included. Below is an example authorize_uri.

https://login.mailchimp.com/oauth2/authorize?response_type=code&client_id=635959587059&redirect_uri=http%3A%2F%2F192.168.1.8%2Foauth%2Fcomplete.php

The user is prompted to enter their username and password to approve your application. ‘Remember me’ cookies are not used here. Mailchimp redirects back to your redirect_uri as a GET request with the code parameter.

Upon successful authentication, Mailchimp redirects to the redirect_uri provided, along with a code that you can swap for an access_token.Below is the full URL Mailchimp redirects the user back to, including the code parameter described in the earlier section.

http://192.168.1.8/oauth/complete.php?code=1edf2589e664fd317f6a7ff5f97b42f7

Your application must make an out-of-band request to the access_token_uri using the value of the code parameter. This should be a POST request. The following should all be POSTed: grant_type, client_id, client_secret, code, and redirect_uri.

We return an access_token, which completes the official OAuth2 flow. Though we return access_token, expires, and scope, you only need to care about access_token.

Below is an example POST request:

curl --request POST \
--url 'https://login.mailchimp.com/oauth2/token' \
--data "grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={encoded_url}&code={code}" \
--include

And the example response:

{"access_token":"5c6ccc561059aa386da9d112215bae55","expires_in":0,"scope":null}

Now you need to make a RESTful request using an OAuth2 client to the metadata url. Because no parameters are required, this is essentially an empty GET request. The Authorization header is the magic here—that’s your access_token.

Below is an example of the GET request:

GET /oauth2/metadata HTTP/1.1
User-Agent: oauth2-draft-v10
Host: login.mailchimp.com
Accept: application/json
Authorization: OAuth 5c6ccc561059aa386da9d112215bae55

And the JSON-encoded POST response:

HTTP/1.1 200 OK
Date: Tue, 16 Aug 2011 15:00:29 GMT
Server: Apache/2.2.14 (Ubuntu)
X-Powered-By: PHP/5.3.2-1ubuntu4.9
Set-Cookie: PHPSESSID=8764d8b5ce6a5279fe0a720e17d0ef54; expires=Tue, 16-Aug-2011 15:24:29 GMT; path=/; secure; HttpOnly
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
Set-Cookie: _AVESTA_ENVIRONMENT=jesse; path=/
P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTR STP IND DEM"
Set-Cookie: PHPSESSDATA=97598361317a27a35adc55c2d3976e5bdd96d5e9%3A1313508269%3AeNoDAAAAAAE%3D; expires=Tue, 16-Aug-2011 15:24:29 GMT; path=/; domain=login.mailchimp.com; secure; httponly
Content-Length: 105
Content-Type: application/json

{"dc":"us1","login_url":"https:\/\/login.mailchimp.com","api_endpoint":"https:\/\/us1.api.mailchimp.com"}

Resources and Samples

• OAuth2 Specification
• Client Libraries
• Omniauth, a Rack-based system for multi-provider external authentication
• Banana-Py for Django applications