Describes how OAuth2.0 is implemented for securing the V3 API

All calls into the Constant Contact V3 API access private data in a users account. This requires that all API calls must be authenticated using the OAuth2 authentication protocol. Here we provide you with an overview of how our OAuth2 implementation works, with links to detailed guides for the Client (Two-legged) and Server (Three-legged) authorization flows.

OAuth2 Terminology

To make sure that we’re all speaking the same language, here are the important terms to know regarding how we do OAuth2.0.

Term Definition
Client flow Use this flow for apps that are considered public clients, such as browser-based or mobile apps, where the client code is downloaded from a web server and executed in the browser or on the mobile device. This flow issues an access_token directly to the client. Client flow does not support refresh tokens - users must authenticate and grant access each time they use the app. See the Implicit Grant and Native Applications sections of RFC 6749.
Server flow Use this flow for apps where the client is running on a web server. This is a redirection-based flow, and client must be able to interact with the resource owner’s user-agent (typically a web browser) and receive incoming requests (via redirection) from the authorization server. This flow issues an access_code to the client, which then exchanges it for an access_token. The server flow supports the use of refresh tokens so that users are required to authenticate and grant access only once. See the Authorization Code Grant section of RFC 6749.
Authorization Server Authenticates the Constant Contact account owner or authorized user, and establishes whether they grant or deny the client’s access request.
redirect_uri Tells the Authorization Server where to send the user once access is granted or denied. You can specify multiple redirect_uri's for your app.
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 as the private key to base64 encode the client_id, with the resulting hash used in the authorization header for all calls to the authentication server to authenticate the request.
response_type used by the client to specify the desired grant type; access_code for the server flow, access_token for the client flow.
access_token Issued by the authorization server in response to a valid access token request (valid API key, properly signed request, and user grants access).
refresh_token A refresh_token is returned with an access_token in the server flow. It is exchanged for a new access_token when the existing token expires; not available for the client flow.
scope Defines the Constant Contact functionality to which the user is granting the application access.

Your app must have OAuth2 functionality

All applications that integrate with the V3 API need to have OAuth2 functionality so that end users can authorize access to their Constant Contact account. Apps that use the client flow will require the user to authenticate and grant access each session, due to the short life of the access_token and no refresh_token support. Apps using the server flow must be able to exchange a refresh_token for a new access_token when the existing token has expired. Refresh tokens are used to authenticate a user without requiring them to re-authenticate and grant access to your app.

OAuth2 access and refresh tokens

access_token

  • are 28 characters long
  • live for up to 24 hours

refresh_token

  • are available only in the server flow
  • are 42 characters long
  • are used to exchange an expired access_token for a new one without users having to log in and grant access

When an access token has expired, we send a 401 Unauthorized response. For apps using the implicit or client OAuth flow, the end user will need to grant access again. For apps using the server OAuth flow, the app must support the use of refresh tokens to retrieve a new access token without forcing your end user to grant access to your app again.

Scope

Scope is supported in the V3 API OAuth2.0 authentication. Currently there is only a single scope, contact_data.

Scope is a composite of:

  • user privileges required to access product functionality
  • product features required while using the API
scope privileges products
contact_data contacts:write, contacts:list:write basic
The campaign_creator role cannot access the API at this time.

Scope is not user selectable

Users cannot pick and choose the scopes to which they are granting access, even when there are multiple scopes available - it’s an all or nothing model.

Checks made during Grant Access flow

When a user logs in and grants access to your app, we check for the following:

  • the user has the required privileges
  • the account is in good standing
  • the account has the required products to use the integration

If any of these checks fail, the authentication server returns a 302 response with appropriate messaging. See the Server and Client flow pages for more information.