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.

  • 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

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

A redirect_uri will also override 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 (i.e.: https://test.example.com/somethingelse.php is valid).

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.
  • 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 http://{dc}.api.mailchimp.com. If you your API wrapper isn’t 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 don’t have access to these keys because they are tied directly to your application. But, the user can de-authorize your 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. 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