Technology partners can access both standard developer endpoints and partner-only endpoints. To securely authenticate with CTCT to get access to endpoints, you must use the OAuth2 authentication protocol. The OAuth2 authentication flow to use differs depending on which type of endpoint (standard or partner) you choose to access.

To get access to standard endpoints, you must provide your app API key using either the OAuth2 server or client authentication flow. In exchange, you receive a bearer access token. The bearer access token is used to authorize you to make API calls to standard endpoints on behalf of your CTCT customers. For more details, see OAuth2 server or client authentication flow.

To get access to partner endpoints, you must provide your partner credentials using the partner OAuth2 client authentication flow. In exchange, you receive a one-hour JSON web token (JWT). The JWT and your API key are used to authorize you to make API calls to partner endpoints.

The JWT automatically expires in one hour (3,600 seconds) and cannot be refreshed. You must re-authenticate each time a JWT expires.

Authentication

To get the JWT required to make V3 API calls to partner endpoints, you must first authenticate your technology partner account with Constant Contact.

Create a Partner Authorization Request

Use the POST /token endpoint to create an URL authorization request (https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token) that uses basic authentication (base64 encoded) to pass data as query parameters (the body of the request is empty).

To create the authorization request, specify the following:

1. The Content-Type header as application/x-www-form-urlencoded.
2. Your partner credentials (partner_client_id and partner_secret) as authorization parameters (partner_client_id:partner_secret) in the Authorization request header.

If you do not include required request headers, a 415 error response code is returned. If you use an invalid partner_client_id or grant_type, a 400 error response code is returned.

Example Partner Authorization Requests

POST https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token

/**
  * This method uses your partner client id and partner secret to retrieve a JWT (JSON Web Token).
  *
  * @param partnerClientId      Your partner client id.
  * @param partnerClientSecret  Your partner secret.
  * @return A JSON string containing a JWT.
  */

public String getPartnerJWT(String partnerClientId, String partnerClientSecret) throws Exception {

       StringBuilder authResult = new StringBuilder();
        

      // Make authorization header with Partner Client ID:Partner Secret and encode
        String credentials = partnerClientId + ":" + partnerClientSecret;
        String auth = "Basic " + Base64.getEncoder().encodeToString(credentials.getBytes());
      
        // Create request URL
        StringBuilder requestUrl = new StringBuilder()
                .append("https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token")
                .append("?grant_type=client_credentials");

        URL authorizeUrl = new URL(requestUrl.toString());
        
        // Open connection
        HttpURLConnection con = (HttpURLConnection) authorizeUrl.openConnection();

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

        // Add Headers
        con.setRequestProperty("Authorization", auth);
        con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

        // Read response from server
        try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
            String inputLine;
            while ((inputLine = in.readLine()) != null) {
                authResult.append(inputLine);
            }
        }
        return authResult.toString();
    }

<?php

$partner_client_id = '{PARTNER_CLIENT_ID}';
$partner_secret = '{PARTNER_SECRET}'

$credentials = base64_encode($partner_client_id + ':' + $partner_secret);
$url = 'https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
    "authorization: Basic $credentials",
    "content-type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$error = curl_error($curl);

curl_close($curl);

if ($error) {
  echo "cURL Error:" . $error;
} else {
  echo $response;
}     

AUTH=$(echo -n "$partnerClientId:$partnerSecret" | base64)

curl --request POST 'https://v3api-partner.auth.us-east-1.amazoncognito.com/oauth2/token?grant_type=client_credentials' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic $AUTH"   

Get the JWT

The partner authorization request returns the JWT as the access_token in the response body. Copy the JWT and use it when making V3 API calls to partner endpoints.

Example Partner Authorization Response

 {
    “access_token”: "*****************.eyJzdWIiOiIxNGFxNWxsNWIxaXQ2ZjYydWVmZW02YXFobiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoidGVzdFwvZm9vIiwiYXV0aF90aW1lIjoxNTI3ODE3MzY2LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV83RThJc3hDR0MiLCJleHAiOjE1Mjc4MjA5NjYsImlhdCI6MTUyNzgxNzM2NiwidmVyc2lvbiI6MiwianRpIjoiYWVlZWY1MGEtYjNiNS00MjAxLTlhOGYtOGI1ZjYzYTBlYmNjIiwiY2xpZW50X2lkIjoiMTRhcTVsbDViMWl0NmY2MnVlZmVtNmFxaG4if.LaWN4NEUrR_2gGANnDx8zINMZteR7-E_moskq__zai5BLNpiCBnVtoLHwVH3FvDFVVesMCBmD02dRhZqXkttxEMUmetFybDtEkH2KWbalOmKvibl5JuPyQEqZ5S4DN9ZUZAqv3X48F2e0Eshck-*******************-0aDBMaMtJU-QMfeFJkN2UgKQhtzi2dbLBB06dQEd6gcxh-*****************"
    “expires_in”: 3600,
    “token_type”: “Bearer”
 }

Make Authorized API Calls to Partner Endpoints

To make authorized API calls to partner endpoints, include the JWT, your API key, and specify the Content-Type to use in the headers as follows:

Example Partner Endpoint Request

The following GET partner/accounts method shows how to use the JWT and API key to make an authorized request to a partner endpoint:

<?php
    
$token = 'JWT_TOKEN'
$api_key = 'API_KEY'
$url = 'https://api.cc.email/v3/partner/accounts'
    
$curl = curl_init();
    
curl_setopt_array($curl, array(
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer $token",
    "x-api-key: $api_key"
  ),
));
    
$response = curl_exec($curl);
$error = curl_error($curl);
   
curl_close($curl);
    
if ($error) {
  echo "cURL Error #:" . $error;
} else {
  echo $response;
} 
   

View the partner endpoint topics to see more code examples.