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 theaccount_read
,account_update
,contact_data
, andcampaign_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 thecode
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
/*
* 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 alwaysauthorization_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;
}
/*
* 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 theAuthorization
header in the formatAuthorization: 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 newaccess_token
when the correspondingaccess_token
expires.token_type
— This value is always set toBearer
.
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_token
— Required. The refresh token that corresponds with the access token you are trying to refresh.grant_type
— Required. The value isrefresh_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;
}
/*
* This method is 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 clientId API Key
* @param clientSecret API Secret
* @param refresh_token Refresh Token
* @return JSON string containing a new access_token and a new refresh_token
*/
public String refreshToken(String clientId, String clientSecret, String refresh_token)
throws IOException {
StringBuilder refreshResult = 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 refresh request URL
StringBuilder refreshUrl = new StringBuilder()
.append("https://idfed.constantcontact.com/as/token.oauth2")
.append("?refresh_token=")
.append(refresh_token)
.append("&grant_type=refresh_token");
URL authorizeUrl = new URL(refreshUrl);
// 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) {
refreshResult.append(inputLine);
}
// Close the stream
in.close();
return refreshResult.toString();
}
Response
access_token
— The response body returns a newaccess_token
value.refresh_token
— The response body returns a newrefresh_token
value.token_type
— The value is always set toBearer
.
Example Response
{
"access_token": "Sfs8qFpt2nIbsmnURtnm3YdOzmcv",
"refresh_token": "s8Mu4hfiwmug7ru4Rcoo4hjkawiw4OUTH2ixvsy3b8",
"token_type": "Bearer"
}