webservices

Basic Authentication Over HTTPs

by Administrator on ‎03-25-2011 10:01 AM

The Constant Contact REST APIs support several authentication models. This page documents the preferred Authentication model - Basic Authentication.

 

The Constant Contact Basic Authentication model:

  • Is supported only over https.
  • Provides a relatively direct mitigation path for pre-existing API adopters who leveraged Digest Authentication.

API Access Using Basic Authentication

 

The Basic Authentication model used in the REST APIs is designed to authenticate both the application developer (via an API Key) and a Constant Contact customer (via that customer's Constant Contact UserName and Password). Authentication credentials are required on each API request.

 

Each application is identified by an API Application Key. The key is a private credential which is directly associated with a single 'developer'. Constant Contact distributes API Keys to developers. To get your first API key, or to get an additional key to cover a subsequent application, simply Request API Access using this Online Form.

 

In addition to the API key, each request must include the authentication information for the account which is being accessed. Specifically, the request must include the Constant Contact UserName and Password for the customer account being accessed.

 

API authentication is based on HTTP Basic Authentication. In order to secure access credentials are they are sent across the network, the Constant Contact API only accepts HTTPS Basic Authentication requests. Authentication requests via HTTP will be rejected.

 

Constructing the HTTP Credentials

 

Most modern browsers and http libraries inherently manage the details of the Basic Authentication. Your application will need to construct a HTTP Username from a concatenation of your API User Key, the "%" character and the Constant Contact customer's UserName. This information is passed with Constant Contact Customer's Password in the HTTP Header and the HTTP library should manage the details. 

 

Converting your Digest Authentication Implementation to a Basic Authentication Implementation

 

Basic Authentication is one of the simplest forms of HTTP Authentication. If your application is using a library to handle Digest Authentication, migrating that application to support Basic Authentication is comprised of two steps.

 

  1. Use HTTPS instead of HTTP - For URI's you use to call any API, use HTTPS instead of HTTP.  However, in the XML body you send in, DO NOT change HTTP to HTTPS (see example below).

    Example
    To update a contact, you use the following URI (note the use of HTTPS instad of HTTP):

    https://api.constantcontact.com/ws/customers/joesflowers/contacts/101
    For the contact information, you would normally get the contact information using GET, update the data you want, and re-use the XML body as below (Note we did not change "http" used in the XML body to "https"):
    <entry xmlns="http://www.w3.org/2005/Atom">
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/101</id>
    <title type="text">Contact: u86597@example.com</title>
    <updated>2008-04-25T19:29:06.096Z</updated>
    <author> </author>
    <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/101">
    <EmailAddress>u86597@example.com</EmailAddress>
    <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
    <ContactLists>
    <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1"></ContactList>
    <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/11"></ContactList>
    <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/12"></ContactList>
    <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/14"></ContactList>
    </ContactLists>
    </Contact>
    </content>
    </entry>
  2. Convert your application to use SSL communications (Handling SSL communication is beyond the scope of this documentation).  Unlike HTTP, which uses port 80, HTTPS uses port 443.  Please ensure that you are communicating over port 443 instead of port 80.

  3. Ensure you are using Basic Authentication instead of Digest Authentication - This commonly consists of simply identifying the appropriate authentication model for your HTTP client. For example, in Java, the most prevalent library is HttpClient. Using this library, switching from Digest authentication to Basic authentication is as simple as changing the following code:

    List authPrefs = new ArrayList(1);
    authPrefs.add(AuthPolicy.DIGEST);
    httpclient.getParams().setParameter(AuthPolicy.AUTH_SCHEME_PRIORITY, authPrefs);

    to

    List authPrefs = new ArrayList(1);
    authPrefs.add(AuthPolicy.BASIC);
    httpclient.getParams().setParameter(AuthPolicy.AUTH_SCHEME_PRIORITY, authPrefs);

    Or in PHP, using the Curl module you'd need to change the following code:

    curl_setopt($session, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);

    to

    curl_setopt($session, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

      The username and password that you pass stays exactly the same as with Digest Authentication. Specifically, you construct the HTTP username from the concatenation of your API User Key, the "%" character and the Constant Contact customer's UserName.