Migration: OAuth 1.0a to OAuth 2.0

Use this endpoint to migrate users of your application from OAuth 1.0a authentication to OAuth 2.0 authentication to access the v1 and v2 Constant Contact API.

Methods:

Click a method to view its documentation

POST

DescriptionTOP

This API allows you to, transparent to the end user, migrate your users with OAuth 1.0a authentication to the OAuth 2.0 authentication flow.

Migration work flow

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. IMPORTANT: Configure all new users to use OAuth 2.0 flow.
  4. Start migrating existing users to OAuth 2.0 flow. 

    NOTE: At this point, any new users that authenticate using OAuth 1.0a cannot be migrated to OAuth 2.0, instead, they will need to manually re-enable your integration. 

  5. Migration complete - all users are OAuth 2.0 authenticated. 
  6. Migrated users will continue to have OAuth 1.0a authentication, so they can continue to use the old_client to access the v1 APIs using OAuth 1.0a authentication if necessary. 

Oauth1.0a to 2.0 migration flow

Before you begin

You need to include the following when making a call to the migration endpoint to receive a new OAuth 2.0 access token:

  1. new_client_id - new Mashery API key if the current API key is a non-Mashery API key, go here for more info.
  2. new_client_secret - client secret associated with the Mashery API key, received when you created the key.
  3. oauth_consumer_key - the OAuth 1.0a value used by the consumer to identify itself to the Service Provider
  4. oauth_token - OAuth 1.0a value used by the consumer to access Protected Resources on behalf of the user, instead of the user's Service Provider credentials.
  5. oauth_signature - OAuth 1.0a value used to verify a request by the service provider. 
  6. oauth_timestamp - the number of seconds since January 1, 1970 00:00:00 GMT.
  7. oauth_nonce - random string unique for requests with the same time-stamp.

If you are not using an application framework such as Spring and it's related library functions, you will need to generate the following OAuth 1.0a Authentication parameters required to make a POST call to the migration endpoint:

  • oauth_signature - OAuth 1.0a value used to verify a request by the service provider, generated by encrypting the signature base string using HMAC-SHA1, using the concatenated, encoded token_secret and consumer_secret, separated by an "&" character, as the key. 
  • oauth_timestamp - the number of seconds since January 1, 1970 00:00:00 GMT.
  • oauth_nonce - random string unique for requests with the same time-stamp.

See RFC 5849 for OAuth 1.0a details, and RFC 6749 for OAuth 2.0.

Who can I migrate?

You can migrate users who meet the following criteria:

  1. The user has OAuth 1.0a authentication.
  2. The user has accessed their account using OAuth 1.0a authentication.
  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 Mashery API key is not disabled.
  7. The redirect_uri associated with the Mashery API key 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 have a Mashery API client that uses OAuth 1.0a - do I need a new API key?

No, if your client has a Mashery API key and has only been used with OAuth 1.0a authentication, you do not need to a new API key for OAuth 2.0 authentication.

I have a Mashery API client that uses OAuth 1.0a - do I migrate?

Yes, you should migrate because OAuth 2.0 authentication is an industry-standard method that is more secure than OAuth 1.0a.

Constructing the migration request

The request payload must be url encoded; set Content-Type to application/x-www-form-urlencoded, and Accept to application/json. 

Request

POST https://oauth2.constantcontact.com/oauth2/oauth1migration
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: OAuth
oauth_consumer_key="dpf43f3p2l4k3l03",
oauth_token="nnch734d00sl2jdk",
oauth_signature_method="HMAC-SHA1",
oauth_signature="tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D",
oauth_timestamp="1191242096",
oauth_nonce="kllo9940pd9333jh",
oauth_version="1.0"


new_client_id=<new_mashery_api_key>&new_client_secret=new_mashery_api_key_secret

Response 

If successfully migrated, we will redirect to the 'Redirect URI' in the DB and append the access_token,token_type and the expiration:

https://example.com/?access_token=f8e20fed-75cf-4f66-9672-63ef67763363&token_type=Bearer&expires_in=306109992

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
X-Powered-By: 
Set-Cookie: p2_sso_cid=l1-sso2; Path=/; domain=.l1.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=/

Error Messages

Any error messages are returned in a JSON formatted array:

[
   {
     "error_key": "error_key",
     "error_message": "message"
   }
]

Response CodesTOP

code

description

302

Migration was successful, new access token was issued

400

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

401

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

403

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

406

Unsupported accept header value, must application/json

415

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

500

Internal server error