Describes the OAuth2.0 server flow

Use this flow for apps where the client is running on a web server. The OAuth 2.0 server authentication flow is used whenever a Constant Contact user uses your integration for the first time, and each time the app needs to exchange a refresh_token for a new access_token. The Constant Contact user must login to their account and give permission to your application to access their Constant Contact data. The Server Authentication flow consists of 2 main transactions:

  • Authorization request
  • Auth service responds with authorization_code
  • Access token request
  • Auth service responds with access_token and refresh_token
v3 OAuth2 Server Flows
v3 OAuth2 Server Flows

Authorization Code Request

An Authorization Request is formed as a GET call to the authorization service. The call provides the client_id (API key), redirect_uri, and response_type. If the call is successful, the authorization service responds with the access_code.

Auth Service Endpoint Method Authentication
https://api.cc.email/v3/idfed GET N/A User authentication is invoked when the user logs in to grant access
Authorization request property Value Description
client_id your_API_key The API key for your application.
redirect_uri url_endcoded_redirect_uri Tells the Authorization Server where to send the user once access is granted. This must be the same redirect_uri associated with your_API_key
scope contact_data The product functionality to which the end user is granting the application access
response_type code Must always be set to code in the server flow.

Example Authorization Code Request URL

(not encoded for readability):

https://api.cc.email/v3/idfed?response_type=code&client_id={client_id}&scope=contact_data&redirect_uri=https://localhost:8888

URL encoded:

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

You can include additional query parameters with an Authorization Code Request by appending them to the redirect URI and encoding them.

Example Authorization Code Request

curl -X GET -i -H "application/x-www-form-urlencoded" "https://api.cc.email/v3/idfed?response_type=code&client_id={client_id}&scope=contact_data&redirect_uri=https%3A%2F%2Flocalhost%3A8888"
      public function CTCTv3Auth($clientId, $redirectURI, $scope)
      {
        $request = new HttpRequest();
        $request->setUrl('https://api.cc.email/v3/idfed');
        $request->setMethod(HTTP_METH_GET);
        $params = array(
          'client_id' =>$clientId,
          'redirect_uri' => $redirectURI,
          'scope' => 'contact_data',
          'response_type' => 'code'
        );
        $request->setQueryData($params);
       
        try {
          $response = $request->send();
          echo $response->getBody();
        } catch (HttpException $ex) {
          echo $ex;
        }
      }

Authorization Code Response

If the user grants access to the application, the authorization server responds by issuing an authorization_code and delivers it by adding it to the query component of the redirect URI:

http://localhost:8888/?code={authorization_code}

The authorization_code has a lifetime of 60 seconds.

Authorization Code Request Error Codes

Error Code Reason Message
302 server_error derelict account The account you are attempting to access is no longer valid, please contact customer support.
302 server_error deactivated user The account you are attempting to access has been cancelled by the account owner.
302 server_error account status Account access blocked, please contact customer support.
302 server_error inadequate user privileges Your role does not have the required privileges to use this application. Contact the account owner.
For example, “The Campaign Creator role cannot access contacts data or endpoints”.
302 server_error inadequate product Account is not using all of the products required by this application.

Access Token Request

The code returned in the Auth Code Response needs to be exchanged for an access_token by making an access token request as follows:

Auth Service Endpoint Method Authentication
https://idfed.constantcontact.com/as/token.oauth2 POST Basic: base64 client_id:client_secret

Access Token Request Properties

Access token request property Value Description
code 30 bytes (~20 char) The authorization code returned in the authorization response
redirect_uri url_endcoded_redirect_uri Tells the Auth Server where to send the user once access is granted. This must be the same redirect_uri associated with your_API_key
grant_type authorization_code Must always be set to authorization_code in the server flow.
client_secret client_secret The client_secret is provided when you register your application and get an API key in the My Applications section of the portal.

Example Access Token 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"
      public function CTCTv3Auth($code, $clientId, $clientSecret, $redirectURI)
{
    $request = new HttpRequest();
    $request->setUrl('https://idfed.constantcontact.com/as/token.oauth2');
    $request->setMethod(HTTP_METH_POST);
    $params = array(
        'code' => $code,
        'redirect_uri' => $redirectURI,
        'grant_type' => 'authorization_code'
        
    );
    $request->setQueryData($params);
    $auth = $clientId . ':' . $clientSecret;
    $credentials = base64_encode($auth);
    $request->setHeaders(['Authorization' => ['Basic ' . $credentials]]);
    try {
        $response = $request->send();
        echo $response->getBody();
    } catch (HttpException $ex) {
        echo $ex;
    }
}

Access Token Response

A successful response to this request contains the following fields:

Field Description
access_token hyphenated hexadecimal string used to make API calls to a users account
refresh_token Exchanged for an access token when current access_token expires
token_type This is always set to Bearer
The access_token has a maximum lifetime of 24 hours (86,400 seconds).

Example Access Token Response

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

Refreshing an Access Token

Use the refresh_token to obtain a new access_token when an access_token expires. Your app must retain the new refresh_token returned in the refresh token response, and discard the old refresh_token so that it will be able to repeat this process each time the access_token expires. When an access_token has expired, calls to the API are returned with a “401 Unauthorized” response. When this occurs, your app will have to refresh the ‘access_token’.

Auth Service Endpoint Method Authentication
https://idfed.constantcontact.com/as/token.oauth2 POST Basic: base64 client_id:client_secret
Refresh token request property Value Description
refresh_token refresh_token The refresh_token provided with the expired access_token in the access token response
grant_type refresh_token Tells the Auth Service you are exchanging a refresh_token for a new access_token.

Example Refresh Token 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"
public function CTCTv3Auth($refreshToken, $clientId, $clientSecret)
{
    $request = new HttpRequest();
    $request->setUrl('https://idfed.constantcontact.com/as/token.oauth2');
    $request->setMethod(HTTP_METH_POST);
    $params = array(
        'refresh_token' => $refreshToken,
        'grant_type' => 'refresh_token'

    );
    $request->setQueryData($params);
    $auth = $clientId . ':' . $clientSecret;
    $credentials = base64_encode($auth);
    $request->setHeaders(['Authorization' => ['Basic ' . $credentials]]);
    try {
        $response = $request->send();
        echo $response->getBody();
    } catch (HttpException $ex) {
        echo $ex;
    }
}

Refresh Token Response

A successful response to this request contains the following fields:

Field Description
‘access_token’ hyphenated hexadecimal string used to make API calls to a users account
‘refresh_token’ Exchanged for an access_token when current access_token expires
‘token_type’ This is always set to Bearer
{
  "access_token": "Sfs8qFpt2nIbsmnURtnm3YdOzmcv",
  "refresh_token": "s8Mu4hfiwmug5ru4Rcoo4hjkawiw3OUTH2ixlsy3b8",
  "token_type": "Bearer"
}