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:

  • authorize_uri https://login.mailchimp.com/oauth2/authorize
  • access_token_uri https://login.mailchimp.com/oauth2/token
  • redirect_uri Client-side, made available to the browser in use.
  • metadata https://login.mailchimp.com/oauth2/metadata

Note

The redirect_uri supports wildcards so you can use data-center-specific information for proper API calls. Wildcards work as long as the redirect_uri is a user-registerable domain under a top-level domain. For example, if you enter https://co.uk/ as a redirect_uri, wildcard support will not work. If you enter https://mydomain.co.uk/, wildcard support will work. Domain detection is based on these criteria.

A redirect_uri also overrides the path portion of a URL, as well. For example, a redirect_uri set to https://test.example.com/oauth.php means that any URI starting with either test.example.com or *.test.example.com will work (e.g., https://test.example.com/somethingelse.php).

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.
  • dc The data center string, like us1, us2. If your API wrapper is data center aware, use access_token-dc as a standard API key.
  • api_endpoint Use https://{dc}.api.mailchimp.com. If you your API wrapper is not datacenter-aware, use this API endpoint and the access_token as your API key.
  • login_url https://login.mailchimp.com

Note

The access_token is used as an API key. Users do not have access to these keys because they are tied directly to your application. But, users can de-authorize an application in Mailchimp, which removes and invalidates the token.

Configuration Information

User-Specific Configuration

  • client_id 635959587059
  • client_secret 0da3e7744949e1406b7b250051ee1a95
  • redirect_uri http://192.168.1.8/oauth/complete.php

Mailchimp Standard OAuth2 Configuration

  • authorize_uri https://login.mailchimp.com/oauth2/authorize
  • access_token_uri https://login.mailchimp.com/oauth2/token
  • base_uri https://login.mailchimp.com/oauth2/

Mailchimp Custom Configuration

  • metadata_uri https://login.mailchimp.com/oauth2/metadata

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