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

Here are some things to know before you begin the OAuth2 process.

• Our server implements 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.
• We don’t expire tokens, so you won’t need to use refresh_token.

Register Your Application

When you’re ready to begin, register your application with Mailchimp:

1. In your Mailchimp account, navigate to the Account page.
2. In the account drop-down menu, click Extras, and choose API Keys.
3. Under the “Developing an App?” heading, click Register and Manage Your Apps.
4. Click Register an App.
5. In the fields provided, input your application’s information and click Create.

When creation is successful, you’ll see an Application created message appear, and 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 don’t 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 three specific endpoints, and one for metadata.

Flow

1. To start your application’s connection to Mailchimp, start by sending the user to the authorize_uri.
2. The user will input their username and password to approve your application. “Remember Me” cookies aren’t permitted here.
3. After the user authorizes your application, our server will redirect your user back 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. Our 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.
7. Our server will return a datacenter string, API endpoint, and login URL, as described in the following list.

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. This snippet shows 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 aren’t used here. We will redirect back to your redirect_uri as a GET requests with the code parameter.

Upon successful authentication, we redirect the user back to the redirect_uri provided, along with a code that you can swap for an access_token. The following snippet shows the full URL we redirected 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.

These snippets show 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.

The following example shows 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