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_idRequired. 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_uriRequired. The URI that Constant Contact redirects the user to after they grant access to your application. For more information, see the Authentication Overview page.
  • scopeOptional. A list of the scopes that your application requires. The V3 API currently supports the 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_typeRequired. 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
/*
 * 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;

}

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.

User Permission Request Screen

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

  • codeRequired. Enter the authorization code that Constant Contact returns to your redirect uri in the authorization request response.
  • redirect_uriRequired. Enter the redirect uri that you used as part of the authorization request URL.
  • grant_typeRequired. The value is always authorization_code. This value specifies that the request is part of the server flow.

Example Request

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;
}

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.

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 your application’s API key. For example, the authorization header will look like:

Authorization: Basic MjdlOPBkNjktUmQ4MY00MGUwLWVmZmYtODRjZjM2

Request Parameters

  • refresh_tokenRequired. The refresh token that corresponds with the access token you are trying to refresh.
  • grant_typeRequired. The value is refresh_token. This specifies that the request is for refreshing an access token.

Example Request

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?refresh_token={refresh_token}&grant_type=refresh_token"
/*
 * This function can be used to exchange a refresh token for a new access token and refresh token.
 * Make this call by passing in the refresh token returned with the access token.
 * The response will contain a new 'access_token' and 'refresh_token'
 */

/***
 * @param $refreshToken - The refresh token provided with the previous access token
 * @param $clientId - API Key
 * @param $clientSecret - API Secret
 * @return string - JSON String of results
 */
function refreshToken($refreshToken, $clientId, $clientSecret) {
    // Use cURL to get a new 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 . '?refresh_token=' . $refreshToken . '&grant_type=refresh_token';
    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;
}

Response

  • access_token — The response body returns a new access_token value.
  • refresh_token — The response body returns a new refresh_token value.
  • token_type — The value is always set to Bearer.

Example Response

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