Describes the Authorization Code Flow.

Use the OAuth2 Authorization Code Flow for traditional web applications (your application runs on a web server and executes on a server) and is able to safely store the client secret. Being a redirect-based flow, the client must be able to interact with the resource owner’s user-agent (typically a web browser) and receive incoming requests (via redirect) from the Constant Contact Authorization Server.

Because the Authorization Code Flow passes the access token directly to the web server that hosts the client application rather than to the user’s web browser, it is considered the most secure OAuth2 flow.

Using the Authorization Code Flow, you create an authorization request to allow users to authorize your application to use their Constant Contact data. After users grant your application access to their data, Constant Contact sends you an access token that you use to make V3 API requests, and a refresh token. The refresh token is used to extend the life of the access token without requiring users to re-authenticate their Constant Contact account and reauthorize your application to use their data. When you get a new access token, you should always decode it to validate the access token claims and expiration.

In order to use the Authorization Code Flow, you must first create and configure a V3 API application. For more information, see the Quick Start Guide.

To use the Authorization Code Flow for authorization, complete the steps that follow.

Step 1: Create an Authorization Request

Create the authorization request used to direct users to Constant Contact to authenticate their user account and authorize your application to access their Constant Contact data.

To create an authorization request, make a GET call to the authorization endpoint https://authz.constantcontact.com/oauth2/default/v1/authorize and include all required request query parameters.

For example, the following shows an encoded URL authorization request:

https://authz.constantcontact.com/oauth2/default/v1/authorize?client_id={your_client_id}&redirect_uri=https%3A%2F%2Flocalhost%3A8888&response_type=code&scope=contact_data%20campaign_data%20offline_access&state=235o250eddsdff

Request Parameters

URL encode all request parameters.

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. Specify the absolute URI that you want Constant Contact to use when redirecting a user to your application. After a user authorizes your application, Constant Contact redirects the user to your application and appends the authorization code and state (and optionally the scope) values to the URI as query parameters. Wildcards are not supported except at the domain root level. For more information, see the Authentication Overview page.
response_type — Required. This flow uses code as the value to request an authorization code from Constant Contact.
state - Required. To prevent cross-site request forgery, specify the arbitrary state string value you want to use to uniquely identify a user’s session.
scope — Optional. A list of the scopes that your application requires. The V3 API currently supports the account_read, account_update, contact_data, offline_access, and campaign_data scopes. Scope names must be space-delimited. For example: {contact_data%20campaign_data%20offline_access}.

The offline_access scope is required for returning refresh tokens. For more information on scopes and the specific scopes required by each V3 API endpoint, see the Scopes Overview page.
nonce — Optional. For the purpose of mitigating replay attacks, specify the string value to use to associate a client session with an id_token. The id_token includes information (claims) about the user and, if specified, the nonce value. The id_token is encoded as a JWT and returned in the response when you request an access token. To verify the nonce string value, decode the id_token.

Example Authorization Request

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.
 * The account owner is then redirected to your redirect URL with the authorization code and state appended as query parameters. e.g.:
 * http://localhost:8888/?code={authorization_code}&state={encoded_string_value(s)}
 */

/**
 * @param $redirectURI - URL Encoded Redirect URI
 * @param $clientId - API Key
 * @param $scope - URL encoded, plus sign delimited list of scopes that your application requires. The 'offline_access' scope needed to request a refresh token is added by default.
 * @param $state - Arbitrary string value(s) to verify response and preserve application state
 * @return string - Full Authorization URL
 */

function getAuthorizationURL($clientId, $redirectURI, $scope, $state) {
    // Create authorization URL
    $baseURL = "https://authz.constantcontact.com/oauth2/default/v1/authorize";
    $authURL = $baseURL . "?client_id=" . $clientId . "&scope=" . $scope . "+offline_access&response_type=code&state=" . $state . "&redirect_uri=" . $redirectURI;

    return $authURL;

}

/*
 * 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.
 * The account owner is then redirected to your redirect URL with the
 * authorization code and state appended as query parameters. e.g.:
 * http://localhost:8888/?code={authorization_code}&state={encoded_string_value(s)}
 */

/**
 * @param redirectUri - URL Encoded Redirect URI
 * @param clientId    - API Key
 * @param scope       - URL encoded, plus sign delimited list of scopes that
 *                    your application requires. The 'offline_access' scope
 *                    needed to request a refresh token is added by default.
 * @param state       - Arbitrary string value(s) to verify response and
 *                    preserve application state
 * @return            - Full Authentication URL
 */

public String getAuthorizationURL(String redirectUri, String clientId, String scope, String state) {

    // Create authorization URL
    StringBuilder authUrl = new StringBuilder()
            .append("https://authz.constantcontact.com/oauth2/default/v1/authorize")
            .append("?client_id=")
            .append(clientId)
            .append("&scope=")
            .append(scope)
            .append("+offline_access")
            .append("&response_type=code")
            .append("&redirect_uri=")
            .append(redirectUri)
            .append("&state=")
            .append(state);

    return authUrl.toString();
}

Step 2: Get Authorization

Add the authorization request to your application to direct users to Constant Constant where they are prompted to sign in to authenticate their user account. Next, Constant Contact displays the Permission Request screen allowing the user to authorize your application to access the Constant Contact data that your application requests.

Step 3: Get 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 the authorization code and state values (and optional scope values), as query parameters. For example:

 `http://localhost:8888/?code=lN1WhAHX9ooSIfuhy0LzWJhv713O&state=235o250eddsdff&scope=contact_data`

Step 4: Get the Access Token and Refresh Token

Make a POST request to the https://authz.constantcontact.com/oauth2/default/v1/token token endpoint to exchange the authorization code for an access and refresh token.

Request Parameters

code — Required. Enter the authorization code that Constant Contact returns to your redirect URI in the authorization request response. Authorization codes expire after 5 minutes (300 seconds).
redirect_uri — Required. The absolute URI that Constant Contact redirects the user to after they grant access to your application. Wildcards are not supported except at the domain root level. For more information, see the Quick Start Guide page.
grant_type — Required. The value is always authorization_code. This value specifies that the request is part of the Authorization Code Flow.

Header Formats

In the header, specify the preferred response formats to return as follows:

"Accept", "application/json"
"Content-Type", "application/x-www-form-urlencoded"

Authentication

This request requires basic authentication. Base64 encode the string client_id:client_secret and provide it in the Authorization header of the request. The client_id is the API Key for your application. You can obtain the client_id and client_secret values for your application on the My Applications page.

For example:

`Authorization: Basic MjdlOPBkNjktUmQ4MY00MGUwLWVmZmYtODRjZjM2`

Example Request

PHP JAVA cURL

curl -X POST -i -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic {base64 client_id:client_secret}" "https://authz.constantcontact.com/oauth2/default/v1/token?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://authz.constantcontact.com/oauth2/default/v1/token';

    // Create full request URL
    $url = $base . '?code=' . $code . '&redirect_uri=' . $redirectURI . '&grant_type=authorization_code';
    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, and set the Content-Type header
    $authorization = 'Authorization: Basic ' . $credentials;
    curl_setopt($ch, CURLOPT_HTTPHEADER, array($authorization, 'Content-Type: application/x-www-form-urlencoded'));

    // 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'
 */

/**
 * @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
 * @throws InterruptedException
 * @throws IOException
 * @throws URISyntaxException
 */

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

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

    // Create request URL
    StringBuilder requestBuilder = new StringBuilder()
            .append("https://authz.constantcontact.com/oauth2/default/v1/token")
            .append("?code=")
            .append(authCode)
            .append("&redirect_uri=")
            .append(redirectUri)
            .append("&grant_type=authorization_code");
    URI requestUri = new URI(requestBuilder.toString());
           

    HttpClient httpClient = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder(requestUri)
            .POST(HttpRequest.BodyPublishers.ofString(""))
            .header("Accept","application/json")
            .header("Content-Type", "application/x-www-form-urlencoded")
            .header("Authorization", authHeader)
            .build();
    HttpResponse<String> httpResponse = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
    return httpResponse.body();
}

Example Response

{
    "token_type": "Bearer",
    "expires_in": 28800,
    "access_token": "eyJraWQiOiIzSDdLVVpkSDlyNTh6RVVDSzNYMlR1b2o0SjV0eldWUF9FRUxQTDd6X3hjIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULkZ6YUUtTVFFb2dKQ1VzZlhSUGtBZldobDllckJndVlYRWphOGFXd1RyRzgiLCJpc3MiOiJodHRwczovL2lkZW50aXR5LmNvbnN0YW50Y29udGFjdC5jb20vb2F1dGgyL2F1czFsbTNyeTltRjd4MkphMGg4IiwiYXVkIjoiaHR0cHM6Ly9hcGkuY2MuZW1haWwvdjMiLCJpYXQiOjE2NDQ0Mjc3NzMsImV4cCI6MTY0NDQ1NjU3MywiY2lkIjoiY2M5NGMyZDYtNmU3MC00MjZjLWFmZDEtNzFjOGZhNWY0ODkwIiwidWlkIjoiMDB1MWlieDhsaGIzYW12SFIwaDgiLCJzY3AiOlsiYWNjb3VudF9yZWFkIiwiZW1haWwiLCJjYW1wYWlnbl9kYXRhIiwicHJvZmlsZSIsImFkZHJlc3MiLCJjb250YWN0X2RhdGEiLCJvcGVuaWQiXSwic3ViIjoiZ2Vla3NxdWFkIiwicGxhdGZvcm1fdXNlcl9pZCI6ImQzYTA2ZTYyLTJmMTQtNGQ5Ni05NDUzLTI2NTkxYWI1M2YwZCJ9.saJxgUYx1_OKUteH01KV71vzjaxqTKnZ3XfD4QKtsIkjrmcf4tUWEFSzjuF1kdxLvlMoCyr_MwO81ApwYX2UU0YRhkVsfw2VLR4KpO89ILul7ZJZyzzsVKak8BrgLhqR1AB7X116VRjsH74vD4D-1e4uKKUlK4yefsZE14kFgDZNi74_WPn5FBGeicwMsStdG3qms8X-6LqIxuZ5fXgSxK9wDEBe-xJfJSqAqo1vJKMqw2JT_NvBBLDXqoSg0_q_0IqbxXEMHdX2J_DHGKrY7w1QQGmeBU_BIlewQPUxUGX-dbRavxncBpItt1tsRLBIiPbPkQ_zDN8_J9lPIxJksA",
    "scope": "account_read offline_access",
    "refresh_token": "HFsqfgtZuGyffnD2qb-AQKWDURWAXM8hlgYIFEwaq4E",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMDEyMzQ1ejRXMzhHS3BPMGg3IiwibmFtZSI6IkpvaG4gRG9lIiwiZW1haWwiOiJqZG9lQGFiYy5jb20iLCJ2ZXIiOjEsImlzcyI6Imh0dHBzOi8vaWRlbnRpdHkuY29uc3RhbnRjb250YWN0LmNvbS9vYXV0aDIvYXVzengwNm81alJlZlE4RjQwaDciLCJhdWQiOiJmYThhMDZkYy1iMDAwLTQ3NWMtYWNlZC01NWNlYzVhZWUzMjUiLCJpYXQiOjE2NDQ4NTc4NDcsImV4cCI6MTY0NDg2MTQ0NywianRpIjoiSUQuRFhRQ2pxQmd3M28xMnVHdlN5R2ZpQTJ2QjVFcGNvSktsajBqbFhSc2lqayIsImFtciI6WyJwd2QiXSwiaWRwIjoiMDBvbnBtc2prYmdPc0wydlcwaDciLCJub25jZSI6Ijg2MDgyNTYwMyIsInByZWZlcnJlZF91c2VybmFtZSI6Impkb2UiLCJhdXRoX3RpbWUiOjE2NDQ4NTc4NDQsImF0X2hhc2giOiJuWk5sRjduWGo2bV9UNEFKcXl0c1RRIn0.ToO_Ye1YHRx4hWCMBnrT6yksWvkrpHfGmXcHTh7B75A"
}

token_type — This value is always set to Bearer.
expires_in — The number of seconds remaining until the access_token expires.
access_token — The new access_token value used to send requests with the V3 API. Access tokens automatically expire 1440 minutes (86,400 seconds). Making an API call with an expired access token returns a 401 unauthorized status code.
scope — The type of data in Constant Contact that the user is granting your application permission to use. The offline_access scope is required to get a refresh token.
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.
id_token — The JWT that includes information about the user such as their name and email address, and if specified, the nonce value you passed in the authorization request. Decode the id_token to verify the nonce value and view user information.

Step 5: Validate the Access Token

For each new access token that you receive, follow best security practices by validating the signature and claims for the access token by completing the procedures that follow.

Load the JSON web-key Set

Use the method that follows to load the Constant Contact public JSON web-key set used to get the access token.

/**
    * This method uses the java11 http client to load Constant Contact's public json web key set.
    * In real use cases, this value should be cached.
    * @return Constant Contact's public json web key set for the v3 API.
    */
   public String getPublicJsonWebKeySet() throws IOException {
       HttpClient httpClient = HttpClient.newHttpClient();
       HttpRequest request = HttpRequest.newBuilder(URI.create("https://identity.constantcontact.com/oauth2/aus1lm3ry9mF7x2Ja0h8/v1/keys"))
               .GET()
               .header("Accept","application/json")
               .header("Content-Type", "application/x-www-form-urlencoded")
               .build();
       HttpResponse<String> httpResponse = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

       return httpResponse.body();
   }

Verify the Access Token Claims

Use the method that follows to parse the access token, and then validate the signature and claims of the access token. The code examples in this step use the org.jose4j library.

Use the jwt parameter to pass in the access token.
Use the jsonWebKeySetJson parameter to pass the JSON Web Key Set (JWKS) value (this is the value that was returned in the previous Load the JSON web-key set step).

   /**
    * This method uses the jose4j library to verify the claims on the JWT.
    * It throws an exception if it fails to parse the JWT, or the JWT does not include the expected claim.
    * @param jwt String containing a JSON web token.
    * @param jsonWebKeySetJson the set of keys available at https://identity.constantcontact.com/oauth2/aus1lm3ry9mF7x2Ja0h8/v1/keys
    * @throws JoseException
    * @throws InvalidJwtException
    */
   public void verifyJwtToken(String jwt, String jsonWebKeySetJson) throws JoseException, InvalidJwtException {

       JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jsonWebKeySetJson);
       VerificationJwkSelector jwkSelector = new VerificationJwkSelector();
       JsonWebSignature jws = new JsonWebSignature();
       jws.setCompactSerialization(jwt);

       JsonWebKey jwk = jwkSelector.select(jws, jsonWebKeySet.getJsonWebKeys());

       JwtConsumer jwtConsumer = new JwtConsumerBuilder()
               .setRequireExpirationTime()
               .setRequireSubject()
               .setExpectedIssuer("https://identity.constantcontact.com/oauth2/aus1lm3ry9mF7x2Ja0h8")
               .setExpectedAudience("https://api.cc.email/v3")
               .setVerificationKey(jwk.getKey())
               .setJwsAlgorithmConstraints(AlgorithmConstraints.ConstraintType.PERMIT, AlgorithmIdentifiers.RSA_USING_SHA256)
               .build();

       jwtConsumer.processToClaims(jwt);
   }

If the access token is not valid or if a required claim is missing or incorrect, an exception occurs.

Check the following claims:

Compare the cid (client identifier) value to ensure that it matches your application API key
The platform_user_id claim in the access token uniquely identifies a Constant Contact user.

To check the claims, use the previous code example, except replace jwtConsumer.processToClaims(jwt); with the following:

JwtClaims claims = consumer.processToClaims(token);

String cid = claims.get("cid")
  if (! apiKey.equals(cid)) {
  throw new InvalidJwtException("Api key in token incorrect");
}
String userId = claims.get("platform_user_id")
  if (userId == null) {
  throw new InvalidJwtException("Token is missing platform_user_id");
}  

Step 6: Add the Access Token to the Authorization Request

After verifying the access token claims and signature, use the access token to send requests in the V3 API by adding it to the Authorization request header in the format Authorization: Bearer {your_access_token}.

If the access token expires, users must reauthenticate and reauthorize your application through Constant Contact. Making an API call with an expired access token returns a 401 unauthorized status code.

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

Step 7 (Optional): Check the Access Token Expiration Timestamp

You can quickly check to see if the access token is expired using the method that follows.

Use the jwt parameter to pass in the access token. This method returns True for an expired token if the expiration time is within 5 minutes (300 seconds) of the current time, or False if the token has not expired. If the access token expires, you can exchange it for a new access and refresh token using the Refresh the Access Token procedure.

  /**
     * This method checks if the current time is greater than or equal to the JWT expiration claim.
     * @param jwt A String JSON web token.
     * @return True if the jwt token is expired. False if the token is not expired.
     */
    public boolean checkIfTokenIsExpired(String jwt) throws InvalidJwtException, MalformedClaimException {

        JwtConsumer jwtConsumer = new JwtConsumerBuilder()
                .setRequireExpirationTime()
                .setSkipDefaultAudienceValidation()
                .setDisableRequireSignature()
                .setSkipSignatureVerification()
                .build();
         JwtClaims jwtClaims = jwtConsumer.processToClaims(jwt);
         return NumericDate.now().getValue() >= jwtClaims.getExpirationTime().getValue();
    }

Step 8: Refresh the Access Token

To avoid having to prompt a user to re-authenticate with Constant Contact due to an expired access token, use the refresh token to get a new access token and a new refresh token. To refresh the access token, send a POST request to the https://authz.constantcontact.com/oauth2/default/v1/token authorization endpoint.

Constant Contact rate limits the Token endpoint. A 429 response will likely be returned if you attempt to refresh an access token before every V3 API request. Constant Contact recommends that you only send a refresh token request to get a new access token if your existing access token is expired or about to expire.

Request parameters

refresh_token — Required. The refresh token corresponds to the access token you are trying to refresh.
grant_type — Required. The value is refresh_token. This specifies that the purpose of this request is to refresh an access token.