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. 

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"
   }
]

DescriptionTOP

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.

Workflow

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. 
   
   NOTE: 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. 

Request

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


Response 

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
X-Powered-By: 
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