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.
To make sure that we’re all speaking the same language, here are the important terms to know regarding how we do OAuth2.0.
|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
|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
|Authorization Server||Authenticates the Constant Contact account owner or authorized user, and establishes whether they grant or deny the client’s access request.|
||Tells the Authorization Server where to send the user once access is granted or denied. You can specify multiple
||This is the API key for your integration.|
||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
||used by the client to specify the desired grant type;
||Issued by the authorization server in response to a valid access token request (valid API key, properly signed request, and user grants access).|
||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
- are 28 characters long
- live for up to 24 hours
- are available only in the server flow
- are 42 characters long
- are used to exchange an expired
access_tokenfor 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 is supported in the V3 API OAuth2.0 authentication. Currently there is only a single scope,
Scope is a composite of:
- user privileges required to access product functionality
- product features required while using the API
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