Our v3 API is now available! Learn more by visiting the v3 developer portal. Creating new v2 API keys is no longer supported.

Migration: Basic to OAuth2

Use this endpoint to migrate users of your application from basic authentication to OAuth 2.0 authentication to access either the v1 or v2 Constant Contact API.


Click a method to view its documentation



This API allows you to migrate your users with basic authentication to the OAuth 2.0 authentication flow in a manner that is transparent to the user.


This is the work flow you need to follow in planning your migration to OAuth 2.0.

  1. Get a Mashery API key if you don't have one already.
  2. In your app, build the OAuth 2.0 grant access flow.
  3. Configure all new users to use OAuth 2.0 flow.
  4. Start migrating existing users to OAuth 2.0 flow. 

    : At this point, if any new users gets authenticated using basic authentication, you will not be able to migrate them to OAuth 2.0. 

  5. Migration complete - all users are OAuth 2.0 authenticated. 
  6. Migrated users will continue to have basic authentication, so they can continue to use the old_client_id (defined below) to access the v1 APIs using basic authentication if necessary.

Before you begin

You will need the following for each user migration that you want to perform:

  1. old_client_id - Mashery or non-Mashery API key that has only been used with basic authentication
  2. old_client_secret - client secret associated with the old_client_id
  3. user_name - Constant Contact username of the user being migrated  
  4. user_password - Constant Contact password of the user being migrated
  5. new_client_id - new Mashery API key if the old_client_id is a non-Mashery API key.
  6. new_client_secret - client secret associated with the new_client_id.

Who can I migrate?

You can migrate users who meet the following criteria:

  1. The user has basic authentication.
  2. The user has accessed their account using basic authentication with the old_client_id.
  3. The user's account status is Active. 
  4. The user has not already been migrated.
  5. The user does not have an OAuth 2.0 access token associated with the old_client_id.
  6. The old or new API Key is not disabled.
  7. The redirect_uri associated with the Mashery API Key during the registration process is in the form of http://www.example.com or https://www.example.com. Do not include additional parameters in the base redirect URI.

How do I get a Mashery API key?

You need to create a Mashery account if you don't have one, and register your client/application. Go here for details.

I already have a Mashery API client that uses basic auth - do I migrate?

Yes, you should migrate because OAuth2 authentication is an industry-standard method that is more secure than basic authentication. If your client has a Mashery API key and has only been used with basic authentication, you do not need to get a new Mashery API key.

Constructing the request

The request payload needs to be url encoded; set the header Content-Type to application/x-www-form-urlencoded. The API processes this information using the OAuth2 flow described here


Post https://oauth2.constantcontact.com/oauth2/basicmigration
Accept: application/json
content-type: application/x-www-form-urlencoded
old_client_id=d25ea2377ba6418c817aff50& old_client_secret=10F6F3398A5685DA49A41C20FB8E8D66& user_name=Websd3378af3-1dda-420131031113713926& user_password=123456&new_client_id=d25ea2377ba6418c817aff50 &new_client_secret=10F6F3398A49A41C20FB8E8D66


Any error messages are returned in JSON format. According to the standard Oauth 2.0 flow, you'll find the access_token required for API access in the Location header of the 302 redirect response returned from the POST request to the Migration API.

ResponseHTTP/1.1 302 Moved Temporarily
Date: Thu, 31 Oct 2013 15:37:17 GMT
Server: Apache
Set-Cookie: p2_sso_cid=l1-sso2; Path=/; domain=.constantcontact.com; Secure; HttpOnly
Location: http://localhost.com?access_token=12fcf96c-b7ca-4fca-b3d6-1cf4e2dfdd03&token_type=Bearer&expires_in=315359999
Content-Language: en-US
Content-Length: 0
Vary: Accept-Encoding,User-Agent
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate, no-cache="Set-Cookie"
Pragma: no-cache
Keep-Alive: timeout=10, max=100
Connection: Keep-Alive
Content-Type: text/plain
Set-Cookie: BIGipServerL1_OAUTH2=2556957706.20480.0000; path=/

Response CodesTOP




Migration was successful, new access token was issued


Bad Request; either the request was malformed, the new_client_id is not a Mashery API key, or the redirect_uri was invalid


Authentication failure; either the client or the user cannot be authenticated


Forbidden; the client or the user do not meet the migration requirements


Unsupported accept header value, must application/json


Unsupported content-type in header, must be application/x-www-form-urlencoded


Internal server error