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:
- In your Mailchimp account, navigate to the Account page.
- In the account drop-down menu, click Extras, and choose API Keys.
- Under the “Developing an App?” heading, click Register and Manage Your Apps.
- Click Register an App.
- 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
- To start your application’s connection to Mailchimp, start by sending the user to the
authorize_uri
. - The user will input their username and password to approve your application. “Remember Me” cookies aren’t permitted here.
- 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 anaccess_token
. The code is valid for 30 seconds. - Your application should then make an out-of-band request to the
access_token_uri
using the code our server provided. - Our server returns an
access_token
, which completes the official OAuth2 flow. - To complete the Mailchimp flow, make another RESTful request using an OAuth2 client to the
metadata_uri
. - 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
https://{dc}.api.mailchimp.com
. If you your API wrapper isn’t datacenter-aware, use this API endpoint and theaccess_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
- OAuth2 Specification
- Client Libraries
- Omniauth, a Rack-based system for multi-provider external authentication
- Banana-Py for Django applications