Applications that integrate with Constant Contact using the V3 API, must use the OAuth2 authorization protocol to securely authenticate a Constant Contact user account, and to be granted access to that user’s data.
Before you can configure OAuth2 for your integration, you must first create your application in the V3 API Developer Portal on the My Applications tab. For details, see Create an Application Integration.
OAuth2 Terminology
To better understand OAuth2 flows, review the following related terminology:
Term | Definition |
---|---|
Authorization Server | Authenticates the Constant Contact account owner or authorized user, and establishes whether they authorize the client application access to their Constant Contact data. |
Scopes | Specifies the type of Constant Contact data that the user is granting your application permission to use. For example, the contact_data scope grants your application permission to read a user’s contacts, write to their contacts, and view contact reports. |
Public Client Applications | Native and single-page applications that run on devices or desktop computers or in a web browser and that cannot safely store the client secret. For example, client-side JavaScript applications and mobile applications. |
Traditional Web Applicatons | Applications that allow you to safely store the client secret and that run on a server. For example: Express.js or ASP.NET applications. |
client_id |
This is the API key for your integration. |
client_secret |
The secret is provided to you when you register your application and get an API key. It is used to authenticate requests made to the Authorization Server. The client_id and client_secret (client_id:secret ) are base64 encoded and the resulting hash is used in the authorization header for calls made to the Authorization Server. |
access_token |
The access token is required to make V3 API requests to access a user’s Constant Contact data and is issued by the Authorization Server in response to a valid access token request (valid API key, properly signed request, and user grants your application access to their data). Access tokens (JWT) are very long in length (1,000-1,200 characters) and expire after 1440 minutes (86,400 seconds). They have a maximum life of 24 hours. The OAuth2 flow your application uses determines if refresh tokens are supported. |
refresh_token |
Refresh tokens are supported in the Authorization Code and PKCE flows and are used to extend the lifespan of an access token by exchanging it for a new access and refresh token. This eliminates having to request that users log back in to reauthenticate their Constant Contact accounts or reauthorize your application to access their data. Refresh tokens are 42 characters long and expire after 180 days, if never used. The offline_access scope is required for returning refresh tokens. Refresh token requests require basic authentication. If using the Authorization Code Flow, you must base64 encode the string client_id:client_secret and provide it in the Authorization header of the request. |
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. |
redirect_uri |
Tells the Authorization Server where to send the user after they authorize or deny your application access to their Constant Contact data. You can specify multiple redirect_uri's to use for your app. |
The sections that follow provide an overview of the general procedures required to successfully configure your application to use OAuth2.
Select the OAuth2 Flow to Use
The steps in the OAuth2 flows differ depending on where the client application is installed and executed. Successful authorization starts by sending a user authorization request to the Constant Contact Authorization Server, and ends when the server replies back to the client application with the user’s access token. The access token is then used to make calls to the V3 API in order to get access to the user’s Constant Contact data.
Use the table that follows to determine which OAuth2 flow your application should use.
OAuth2 Flows | Authorization Code Flow | Proof Key for Code Exchange (PKCE) Flow | Device Flow | Implict Flow |
---|---|---|---|---|
Supported Client Applications Types | Traditional web applications (such as Express.js or ASP.NET). | Public client applications | Applications which are input constrained or cannot provide a web browser to users, such as a command line application. | Public client applications. Use only if your application already uses the Implicit flow or does not support Web Crypto. |
Get Authorization | GET https://authz.constantcontact.com/oauth2/default/v1/authorize returns the authorization code value appended to the redirect URL returned in the response. |
GET https://authz.constantcontact.com/oauth2/default/v1/authorize returns the authorization code value appended to the redirect URL returned in the response. |
POSTƒ https://authz.constantcontact.com/oauth2/default/v1/device/authorize returns the authorization device_code value in the response. |
GET https://authz.constantcontact.com/oauth2/default/v1/authorize returns the access token value. |
Get the Access Token POST https://authz.constantcontact.com/oauth2/default/v1/token |
Exchange the code value for the access token. Expires after 1440 minutes (86,400 seconds) with a maximum lifetime of 24 hours (86,400 seconds). Type is Bearer token. |
Exchange the code value for the access token. Expires after 1440 minutes (86,400 seconds) with a maximum lifetime of 24 hours (86,400 seconds). Type is Bearer token. |
Exchange the device_code value for the access token. Expires after 1440 minutes (86,400 seconds) with a maximum lifetime of 24 hours (86,400 seconds). Type is Bearer token. |
The token value is the access token and is appended directly in redirect URL. Expires after 480 minutes (28,800 seconds) with a maximum lifetime of 8 hours. Type is Bearer token. |
Use a Refresh Token POST https://authz.constantcontact.com/oauth2/default/v1/token?refresh_token={refresh_token}&grant_type=refresh_token |
Supported. Expires after 180 days. | Supported. Expires after 180 days. | Supported. Expires after 180 days. | Not supported. |
Helpful Links | For more details, see OAuth2 Authorization Code Flow. External reference, see Authorization Code Grant section of RFC 6749. | For more details, see OAuth2 PKCE Flow. External reference, see Proof Key for Code Exchange by OAuth Public Clients sections of RFC 7636. | For more details, see OAuth2 Implicit Flow. External reference, see Implicit Grant and Native Applications sections of RFC 6749. |
To receive incoming requests from the Constant Contact Authorization Server, all Auth2 flows require that the client be able to interact with the resource owner’s user-agent (typically a web browser) .
Create the Authorization Request
To create the authorization request your application uses to direct users to Constant Contact to authenticate their user account and to allow users to authorize your application to access their Constant Contact data, use the https://authz.constantcontact.com/oauth2/default/v1/authorize
endpoint. The query request parameters to include in the authorization request are specific to the OAuth2 flow your application uses.
For more details, see:
When you create the authorization request, you include the scopes your application requires using the scope
query parameter. Scopes allow you to limit your application’s access to user data and to the V3 API endpoints. When your application requests a user’s permission to access their data, Constant Contact uses authorization scopes to determine what information your application needs. For example, if you do not have the contact_data
scope you cannot access the endpoints that use contact data such as /contacts
, /contact_lists
, /contact_custom_fields
, /activities
, or /reports
. The offline_access
scope is required to get a refresh token for Authorization Code and PKCE OAuth2 flows.
After creating the authorization request, add it to your application code to initiate authorization. If the user chooses to grant access to your application, Constant Contact verifies that the appropriate scopes exist for the type of data requested. The account owner or authorized user must either grant access to all of your scopes or decline access to your application. Account owners are more likely to authorize your application to use their data when you request only the data that your application requires.
For more information on scopes and the specific scopes required by each V3 API endpoint, see the Authorization Scopes Overview page.
Authorization
Constant Contact displays the Permission Request screen to the user listing your applications requested scopes. After the user authorizes your application and grants permission to use the data specifed, they are prompted to sign in to their Constant Contact account so that Constant Contact can authenticate and verify that the user’s account is in good standing.
Errors
During the application registration phase, Constant Contact does not return a 400 error for a redirect_uri
. The only time a 400 error is returned for an application is when the redirect_uri
value passed in the authorization request does not match any of the absolute URIs registered for your application on the My Applications tab.
A 400 response is returned if an error occurs during the application validation phase (before the user is prompted to log in). The following lists all valid 400 responses and descriptions:
invalid_client
: The specifiedclient_id
is invalid.invalid_grant
: The specified grant is invalid, expired, revoked, or does not match the redirect URI used in the authorization request.invalid_request
: The request is missing a necessary parameter, the parameter has an invalid value, or the request contains duplicate parameters.invalid_scope
: The scopes list contains an invalid or unsupported value.unsupported_response_mode
: The specified response mode is invalid or unsupported. This error is also thrown for disallowed response modes. For example, if the query response mode is specified for a response type that includesid_token
.
A 302 success or error response is returned when a user attempts to log in. If the authorization request fails, when Constant Contact redirects the user to your redirect_uri
, it appends the error
and error_description
as URL fragments in the authorization response. The error
value specifies the type of error. The error_description
value describes why the error occurred. For example, the following error example shows that the Authorization Server denied access to your application:
`https://example.com?error=access_denied&error_description=The%20resource%20owner%20or%20authorization%20server%20denied%20the%20request`
Use the error
value to communicate to your application’s users why they were not able to authorize your application.
Possible errors attached to the 302 redirect URL include:
access_denied
: The Authorization Server denied the request.consent_required
: The user denied your application access to their Constant Contact data.invalid_token
: The provided access token is invalid.server_error
: The server encountered an internal error.temporarily_unavailable
: The server is temporarily unavailable, but should be able to process the request at a later time.unsupported_response_type
: The specified response type is invalid or unsupported.
Get the Access Token
After successfully authenticating the user and getting the user to authorize your application, Constant Contact redirects the user to your chosen redirect_uri
. If using the Implicit Flow, the access token
is appended to the redirect_uri
. If using the Authorization Code or PKCE flows, the authorization code
is appended to redirect_uri
and must be exchanged for an access token. The code
and can be used once.
To exchange the code
for an access token, send a POST
request to the https://authz.constantcontact.com/oauth2/default/v1/token
authorization endpoint. The parameters to include depend on the OAuth2 flow your application uses.
To make V3 API requests, you must add the access token to the Authorization
request header in the format Authorization: Bearer {your_JWT_access_token}
. When an access token expires, users must reauthorize your application with Constant Contact.
Refresh Token
Refresh tokens are used to extend the lifespan of an access token by exchanging it for a new access and refresh token. This eliminates having to request that users log back in to re-authenticate their Constant Contact accounts or reauthorize your application to access their data.
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.
For more OAuth2 flow specific details, see: