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:
- The
Content-Type
header asapplication/x-www-form-urlencoded
. - Your partner credentials (
partner_client_id
andpartner_secret
) as authorization parameters (partner_client_id:partner_secret
) in theAuthorization
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:
Headers | Description | Example |
x-api-key |
The API key that uniquely identifies your technology partner app. Specify your API key (partner_client_id ) as a URL query parameter. |
ctct1234-cons-tant-cont-act012345678 |
Content-Type |
The content format type to use. | application/json |
Authorization |
The JWT to use to make authorized API calls to account endpoints. | See a JWT in the example that 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.