Understanding how your application uses OAuth2.0 to get secure access to Constant Contact user data through the V3 API

External client apps that integrate with Constant Contact using the V3 API, must use the OAuth2 authentication protocol to securely authenticate a Constant Contact user account, and to be granted access to that user’s data.

Although the steps in the OAuth process flows differ depending on where the client app is installed and executed, successful authentication starts by sending a user authorization request to the Constant Contact Authorization Server, and ends when the server replies back to the client app with the user’s access token.

OAuth2 process flows have the following general steps in common:

  • Step 1: Verify that all prerequisite are met.

  • Step 2: Identify the appropriate OAuth2 flow to use.

  • Step 3: Send the user authorization request URL to Constant Contact.

  • Step 4: Get the token from the redirect URL and use it to get Constant Contact user data through your app.

Verify Prerequisites are Met

Before you can implement OAuth2 functionality for your registered Constant Contact app, verify that the following settings exist:

  • Application settings - As specified on the V3 API Developer Portal My Applications tab:
    • API Key - The unique key used to authenticate calls made from your app to the V3 API. Constant Contact generates the api_key when you register the app.
    • Redirect URI - After the account owner is directed to the Constant Contact Authorization Server to log in and to grant or deny your app access to their data, they are sent to the redirect URI that you specify. You can specify multiple redirect_uri's for your app. URI fragments are not supported.
    • App Secret - Constant Contact generates the app secret when you register the app. The app secret is used, in addition to the API key, to authenticate calls made from your app to the V3 API.
    • App Name - The name you chose to use to identify your application. The app name cannot contain “Constant Contact”.
    • App Logo URL - The URL and app logo to use to give users access to your app.
    • App Description - A useful description that includes how or why users can use your app.
  • Scopes settings - The user account must have the appropriate scopes set to enable access the type of data that your app is requesting, such as contacts_data or campaign_data. For more information on scopes and the specific scopes required by each V3 API endpoint, see the Scopes Overview page.

Identify the OAuth2 Process Flow to Use

The V3 API supports two OAuth2 process flows.

OAuth2 Server Flow

Use the OAuth2 Server Flow (three-legged flow) for apps where the client is running on a web server. Because this is a redirection-based flow, the 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 Constant Contact Authorization Server.

This flow issues an access_code to the client, which then exchanges it for an access_token. The advantage for using the server flow is that it supports the use of refresh tokens; requiring users to only authenticate and grant access once. For more details, see Authorization Code Grant section of RFC 6749.

OAuth2 Client Flow

Use the OAuth2 Client Flow (two-legged 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.

Using this flow, the Authorization Server issues an access_token directly to the client. Unlike the OAuth2 server flow, this flow does not support refresh tokens. Therefore, users must be authenticated and grant access each time they use the app. For more details, see the Implicit Grant and Native Applications sections of RFC 6749.

Send an Authorization Request

Your app sends an authorization request to the V3 API authorization endpoint on the Authorization Server in the form of a URL. To create an authorization request URL, add your values for the following query parameters.

  • client_id - The API key to use for your application.
  • redirect_uri - After the user grants your application permission to the Constant Contact data requested, the Authorization Service sends the user to the redirect_uri that you specify. It must be a redirect_uri that is currently associated with the API key you specified.
  • response_type - Specifies the type of authentication flow that the application uses. Types include:
    • code - Uses the OAuth2 server flow. The code is returned in the authorization response and is approximately 20 characters long (30 bytes).
    • token - Uses the OAuth2 client flow.

When the account owner visits the URL, Constant Contact displays the screen that allows them to log in and grant your application access to their data.

Account Verification

When the user logs in to their Constant Contact account, the Authentication Server verifies that the account is active and is in good standing. If any of these checks fail, the authentication server returns a 302 response with appropriate messaging.

Authorization Request Errors

If the authorization request fails, Constant Contact redirects the user to your redirect_uri and appends an error and error_description as URL fragments. The error value specifies the type of error. The error_description value describes why the error occurred.

Returned error Value Status Code Description
server_error 302 The account you are attempting to access is no longer valid, please contact customer support.
server_error 302 The account you are attempting to access has been cancelled by the account owner.
server_error 302 Account access blocked, please contact customer support.
invalid_scope 302 The authorization request contains scope names that are not supported by the V3 API.
unsupported_response_type 302 The authorization request contains a missing response_type value or a response type value that is not token or code.
access_denied 302 The user chose not to grant your application permission to use their data.

Use the error value to communicate to your application’s users why they were not able to authorize your application.

For example, an authorization response where the user denied access to your application will look like:

https://localhost:8888/#error=access_denied

Grant Access

Constant Contact displays the scopes you requested from a user when they authorize your application.

User Permission Request Screen

Scope examples:

  • contact_data - Grants an application permission to read or write contact data and to read contact reports.
  • campaign_data - Grants an application permission to read or write campaign data.

If the account owner chooses to grant access to your app, Constant Contact verifies that the appropriate scopes exist for the type of data requested. The account owner must either grant access to all of your scopes or decline to grant access to your app. Account owners are more likely to authorize your application to use their data when you request only the data that your application requires. For example, if a user’s email contact information is all that your app requires, limit the data request by specifying the scope (contacts_data) in the Authorization request URL.

If any of these checks fail, the Authentication Server returns a 302 response with appropriate messaging.

Get the Token from the Redirect URL

After the account owner is successfully authenticated and authorizes your application, Constant Contact redirects the account owner to your chosen redirect_uri and appends the authorization code (OAuth2 server flow) or an access token (OAuth2 client flow) to the URL.

Tokens

Using access tokens with a limited lifespan decreases the risk and impact of compromised credentials. Unlike basic authorization, user credentials are not required.

The V3 API supports the following token types:

  • access_token

    • Token is 28 characters long.
    • Used for both OAuth2 flows.
    • Automatically expire two hours (7,200 seconds) after the last use.
    • Has a maximum lifetime of twenty four hours (86,400 seconds).
    • If you use an expired token, Constant Contact sends a 401 Unauthorized response.
  • refresh_token

    • Token is 42 characters long.
    • Only for use in the OAuth2 server flow.
    • Used to extend the lifespan of an access token by exchanging an expired access_token for a new access token without requiring users to log in and grant access.

For details on using OAuth2 flows, see the Server Flow page and the Client Flow page.