Describes the OAuth2.0 server flow

Use the OAuth2 server flow if your application runs on a web server and the source code is not available to the public. In order to use the Oauth2 server flow, your application must be able to safely store the client secret.

After you complete the OAuth2 server flow, Constant Contact returns an access token and refresh token. You can use access tokens to make requests using the V3 API. You can use refresh tokens to obtain new access tokens without any user input. This ensures that your users only need to authenticate once.

In order to use the OAuth2 server flow, you must create and configure a V3 API application. For more information on the prerequisites, see the Authentication Overview.

Authenticate Using the Server Flow

Step 1:Create an Authorization Request URL

Create an authorization request URL by adding your client_id, redirect_uri, response_type, and scope values as query parameters to the https://api.cc.email/v3/idfed authorization endpoint.

client_id — Required. The API key for your application. You can view the API keys for all of your applications or create a new application on the My Applications page.
redirect_uri — Required. The URI that Constant Contact redirects the user to after they grant access to your application. For more information, see the Authentication Overview page.
scope — Optional. A list of the scopes that your application requires. The V3 API currently supports the account_read, account_update, contact_data, and campaign_data scopes. For more information on scopes and the specific scopes required by each V3 API endpoint, see the Scopes Overview page.
response_type — Required. The server flow uses the code value and returns an authorization code in the response.

The finished authorization request URL will look like:

https://api.cc.email/v3/idfed?client_id={your_client_id}&redirect_uri=https%3A%2F%2Flocalhost%3A8888&response_type=code&scope=contact_data+campaign_data

Example Authorization Request URL

PHP JAVA

/*
 * This function can be used to generate the URL an account owner would use to allow your app to access their account.
 * After visiting the URL, the account owner is prompted to log in and allow your app to access their account.
 * They are then redirected to your redirect URL with the authorization code appended as a query parameter. e.g.:
 * http://localhost:8888/?code={authorization_code}
 */

/***
 * @param $redirectURI - URL Encoded Redirect URI
 * @param $clientId - API Key
 * @return string - Full Authorization URL
 */
function getAuthorizationURL($redirectURI, $clientId) {
    // Create authorization URL
    $baseURL = "https://api.cc.email/v3/idfed";
    $authURL = $baseURL . "?client_id=" . $clientId . "&scope=contact_data&response_type=code" . "&redirect_uri=" . $redirectURI;

    return $authURL;

}

/*
  * This method can be used to generate the URL an account owner would use to allow your app to access their account.
  * After visiting the URL, the account owner is prompted to log in and allow your app to access their account.
  * They are then redirected to your redirect URI with the authorization code appended as a query parameter.
  * e.g.: http://localhost:8080/?code={authorization_code}
  */

/**
  * @param redirectUri   URL Encoded Redirect URI
  * @param clientId      API Key
  * @return              Full Authentication URL
  */

public String getAuthenticationUrl(String redirectUri, String clientId){

    // Create authorization URL
    StringBuilder authUrl = new StringBuilder()
        .append("https://api.cc.email/v3/idfed")
        .append(clientId)
        .append("&scope=contact_data")
        .append("&response_type=code")
        .append("&redirect_uri=")
        .append(redirectUri);

    return authUrl.toString();
}

Step 2:Add the Authorization Request URL to Your Application

Add the authorization request URL to your application and direct your application’s users to the URL. Constant Contact then prompts the users to sign in and allow your application to access their data. Constant Contact displays the scopes you requested from a user when they authorize your application.

Step 3:Retrieve the Authorization Code

After a user successfully grants your application access to their data, Constant Contact redirects the user to your chosen redirect uri and appends a code value as a query parameter. The code value is the authorization code that you use to obtain the access token. The authorization code has a 60 second lifetime.

For example, a successful authorization response will look like:

http://localhost:8888/?code=lN1WhAHX9ooSIfuhy0LzWJhv713O

See the Authorization Request Errors table in the Authentication Overview for information on how to handle authorization request errors.

Step 4:Exchange the Authorization Code for an Access Token and a Refresh Token

Send a POST request to the https://idfed.constantcontact.com/as/token.oauth2 authorization endpoint with the code, redirect_uri, and grant_type query parameters.

Authentication

This request requires basic authentication. Base 64 encode the string client_id:client_secret and provide it in the Authorization header of the request. You can obtain the client_id and client_secret values for your application on the My Applications page. The client_id is the API Key for your application. For example, the authorization header will look like:

Authorization: Basic MjdlOPBkNjktUmQ4MY00MGUwLWVmZmYtODRjZjM2

Request Parameters

code — Required. Enter the authorization code that Constant Contact returns to your redirect uri in the authorization request response.
redirect_uri — Required. Enter the redirect uri that you used as part of the authorization request URL.
grant_type — Required. The value is always authorization_code. This value specifies that the request is part of the server flow.

Example Request

PHP JAVA cURL

curl -X POST -i -H "application/x-www-form-urlencoded" -H "authorization: Basic {base64 client_id:client_secret}" "https://idfed.constantcontact.com/as/token.oauth2?code={authorization_code}&redirect_uri={redirect_uri}&grant_type=authorization_code"

/*
 * This function can be used to exchange an authorization code for an access token.
 * Make this call by passing in the code present when the account owner is redirected back to you.
 * The response will contain an 'access_token' and 'refresh_token'
 */

/***
 * @param $redirectURI - URL Encoded Redirect URI
 * @param $clientId - API Key
 * @param $clientSecret - API Secret
 * @param $code - Authorization Code
 * @return string - JSON String of results
 */
function getAccessToken($redirectURI, $clientId, $clientSecret, $code) {
    // Use cURL to get access token and refresh token
    $ch = curl_init();

    // Define base URL
    $base = 'https://idfed.constantcontact.com/as/token.oauth2';

    // Create full request URL
    $url = $base . '?code=' . $code . '&redirect_uri=' . $redirectURI . '&grant_type=authorization_code&scope=contact_data';
    curl_setopt($ch, CURLOPT_URL, $url);

    // Set authorization header
    // Make string of "API_KEY:SECRET"
    $auth = $clientId . ':' . $clientSecret;
    // Base64 encode it
    $credentials = base64_encode($auth);
    // Create and set the Authorization header to use the encoded credentials
    $authorization = 'Authorization: Basic ' . $credentials;
    curl_setopt($ch, CURLOPT_HTTPHEADER, array($authorization));

    // Set method and to expect response
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Make the call
        $result = curl_exec($ch);
        curl_close($ch);
        return $result;
}

/*
  * This method can be used to exchange an authorization code for an access token.
  * Make this call by passing in the code present when the account owner is redirected back to you after authenticating.
  * The response will contain an 'access_token' and 'refresh_token' in a JSON object.
  */

/**
  * @param redirectUri   URL Encoded Redirect URI
  * @param clientId      API Key
  * @param clientSecret  API Secret
  * @param authCode      Authorization Code
  * @return              JSON string containing an access_token and a refresh_token
  */

public String getAccessToken(String redirectUri, String clientId, String clientSecret, String authCode)
        throws IOException {

    StringBuilder authResult = new StringBuilder();

    // Make authorization header with API Key:API Secret and encode
    String credentials = clientId + ":" + clientSecret;
    String auth = "Basic " + Base64.getEncoder().encodeToString(credentials.getBytes());

    // Create request URL
    StringBuilder requestUrl = new StringBuilder()
            .append("https://idfed.constantcontact.com/as/token.oauth2")
            .append("?code=")
            .append(authCode)
            .append("&redirect_uri=")
            .append(redirectUri)
            .append("&grant_type=authorization_code");

    URL authorizeUrl = new URL(requestUrl);

    // Open connection
    HttpURLConnection con = (HttpURLConnection) authorizeUrl.openConnection();

    // Set Method
    con.setRequestMethod("POST");

    // Add Auth Header
    con.setRequestProperty("Authorization", auth);

    // Read response from server
    BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
    String inputLine;

    while ((inputLine = in.readLine()) != null) {
        authResult.append(inputLine);
    }

    // Close the stream
    in.close();

    return authResult.toString();
}

Response

access_token — The access token allows you to send requests with the V3 API. Use the access token by adding it to the Authorization header in the format Authorization: Bearer {your_access_token}. Access tokens automatically expire two hours (7,200 seconds) after their last use. Access tokens have a maximum lifetime of 24 hours (86,400 seconds).
refresh_token — Each refresh token corresponds to an access token. Use the refresh token to obtain a new access_token when the corresponding access_token expires.
token_type — This value is always set to Bearer.

Example Response

{
  "access_token": "Sfs8qFpt2nIbsmnURtnm3YdOzmcv",
  "refresh_token": "s8Mu4hfiwmug7ru4Rcoo4hjkawiw4OUTH2ixvsy3b8",
  "token_type": "Bearer"
}

Step 5:Refresh the Access Token

Refresh an access token by sending a POST request to the https://idfed.constantcontact.com/as/token.oauth2 authorization endpoint with the refresh_token and grant_type query parameters. This allows you to obtain a new access token and a new refresh token without having to prompt the user to reauthenticate with Constant Contact.