OAuth 2.0 Server Flow

The OAuth 2.0 server authentication flow is used whenever a Constant Contact account uses your integration for the first time. The Constant Contact user must login to their account and give permission to your application to access their Constant Contact account. The Server Authentication flow consists of 2 main transactions:

• The app makes an authorization request 
• The authorization server responds with an authorization code.
• The app then makes an access token request using the authorization code.
• The authorization server responds with an access token.

The interactions between the user, the application, and the Constant Contact Authorization Server are illustrated here.

1. The Constant Contact user opens your application for the first time.
2. The application directs the user to the Constant Contact authorization server (see Authorization Request for details).
3. The user authenticates with Constant Contact and grants the application access to their account.
4. The authorization server redirects the user to the application using the redirect URI, and provides an authorization code if the user granted access to the application (see Authorization Response for details).
5. The application then exchanges the authorization code for an access token for use in all API calls for that account (see Access Token Request for details)

For users without a Constant Contact account

You have two options to allow users to sign up for a Contact Contact account if they don't already have one when they launch your app. The first option adds a sign up link to the login page by using the oauthSignup query parameter. The second option allows you to ask users if they have an account when opening your app for the first time. If they answer no, use the newUser query parameter to direct them to the account sign up page. 

Option 1: Using the oauthSignup Query Parameter

Use oauthSignup=true in the Authorization request to display "Dont have an account? Sign up free" in the top right of the login screen. This gives users who don't have an account the ability to sign up for an account and grant access to the new account. 

Login window when oauthSignup=false (see parameters table below for more info)	Login window when oauthSignup=true

Allow Access prompt:

Option 2: Using the newUser Query Parameter

When set to true, the newUser query parameter sends the user to the account signup form to create a new trial account, and then on to the Allow Access screen. This gives you the option to ask the user if they already have a Constant Contact account when they initially launch your app. If they do, you use the traditional grant access flow where the user logs in to their account, and then Allows Access. 

If the user does not have an account, use newUser=true in the Authorization Request to send the user to the Account Signup page. After signing up for a free trial account, the Allow Access screen displays. 

Create Account page shows when using  newUser=true  (see parameters table below for more info)		Allow Access displays after user creates new account.

Authorization Request

An Authorization Request is formed as a GET call to the authorize API endpoint.

oauthSignup

true or false(default)

No

newUser

true or false(default)

No

Example: Authorization Request for the server flow:

GET https://oauth2.constantcontact.com/oauth2/oauth/siteowner/authorize?response_type=code&client_id=187775cfde5143b&
redirect_uri=https%3A%2F%2Fwww.myapplicationurl.com

You can include additional query parameters with an Authorization request by appending them to the redirect URI and encoding it, as follows:

GET https://oauth2.constantcontact.com/oauth2/oauth/siteowner/authorize?
response_type=code&client_id=187775cfde5143ba92187c985fa63dd6&
redirect_uri=https%3A%2F%2Fwww.myapplicationurl.com%3FqueryParam1%3DqueryValue1
%26param2%3Dvalue2%26param3%3Dvalue3

Authorization Response 

If the user grants the access request, the authorization server issues an authorization code and delivers it by adding it to the query component of the redirect URI.

Example: Authorization Response for the server flow 

<your_encoded_redirect_URI>?code=fuOJtFn7K6srQ37wC576A6azI5h&username=<constant_contact_username>

NOTE: If a user's account has been inactive (user never logged in) for the 3.5 years prior to April 1, 2013, it has been deactivated. These accounts cannot be reactivated and are not able to obtain an access token. The Authorization Response for these accounts is:

<your_encoded_redirect_URI>?error=access_denied&error_description=This+account+is+no+longer+valid

Error Codes

These are some of the response codes that the system provides during the authentication flow.

Access Token Request

After the application receives the authorization code, it must exchange it for an access token by making a call to the Token endpoint.

1. The application requests an access token from the Constant Contact authentication server, providing its client_id, client_secret, redirect_URI and the authorization_code.
2. The authorization server validates the client credentials, the authorization code, and the redirect_URI (ut must match the redirect_uri used in the Authorization Request exactly, including any parameters added). If the validation is successful, the authorization server sends back an access token. The application needs to retain the access token and use it when making API calls on behalf of the user.

The request is formed as a POST to the Token endpoint, defined as follows:

Example: Access Token Request for the server flow

POST https://oauth2.constantcontact.com/oauth2/oauth/token?grant_type=authorization_code&client_id=<your_API_KEY>&client_secret=<your_client_secret>
&code=<unique_code>&redirect_uri=<your_redirect_URI>

Access Token Response

A successful response to this request contains the following fields:

A successful response is returned as a JSON array:

{
 "access_token":"a46950a6-7cad-413a-8183-550756d096f4",
 "expires_in":315359999,
 "token_type":"Bearer"
}

OAuth 2.0 Server Flow PHP Example

Check out sample PHP code that implements the OAuth 2.0 server flow in this Github repository.