Overview

Notwithstanding any learning curve an institution web developer or application programmer may have related to familiarity with the programming language they use, the Engage API was designed to be straightforward to use while providing appropriate measures of security. The backbone of this model is reliance on secure HTTP (i.e., HTTPS) and public key cryptography (also referred to as a public/private key exchange). Both a valid digital signature (i.e., a hash value) and a time value accurate to within thirty seconds of the current international time (as obtained from an international time server such as those listed at http://tycho.usno.navy.mil/NTP/ or from your own web service if it is synchronized with a time server) must be included on every request in order for the request to be processed.

There are a number of security benefits this model is meant to provide to institutions:

  • Secure HTTP connections ensure that packet sniffing will not yield any details of your requests to the API in unencrypted form.
  • Encrypted or hashed digital signatures ensure that the “password” (a.k.a., private key) for your API “account” (a.k.a., public key) is never openly transmitted, thus greatly minimizing the potential for a security breach based on the unlikely event of discovery and misuse of institution credentials.
  • Request expirations ensure that all requests made to the API will only be processed if they occur within thirty (30) seconds of the time value sent in the request and included in the hashed digital signature. In the unlikely event a malicious user were to monitor institutional API requests and attempt to reproduce (or “spoof”) them, the API would not process such requests due to the expiration of the time window.
  • The hash is made up of static and dynamic values which change on each request making it nearly impossible for brute force attacks to work.

How to Connect / Authenticate

The authentication process used by the Engage API is not based on a username and password as might be the case with a website or web application. Rather, institutions using the API must include a number of specific pieces of information  when making a request for data, so that the API can verify the authenticity of a request. The parameters that must be included in every request sent to the API are:

  1. The current time (represented in 13-digit milliseconds/UTC format, e.g. the date/time of "7/27/2013 9:02:00" would be sent as "1374930120000")
  2. A valid public key assigned to the institution
  3. A random string such as a GUID
  4. A digital signature (i.e., hash value) consisting of:
    1. the public key
    2. the IP address of the server from which your code is run
    3. the current time
    4. any random string such as a GUID
    5. the private key

The following cryptographic hash functions are supported: MD5, SHA-256, SHA-384, and SHA-512

The items above should be added as parameters on the request URL (e.g., https://yourinstitution.campuslabs.com/engage/api/organizations?time="__"&apikey="__"&random="__"&hash="__"). The code you would write to authenticate and request the list of organizations from your system would look something like this:

// Start Pseudo Code

// Read the current time from your server and convert it to milliseconds to create a 13-digit string value
$now = time();
$time = convert_to_milliseconds($now);

 

// When using IP address restriction, you could include it as a hard-coded string or get it dynamically
$ipaddress = get_server_ip();

 

// This is the "username" half of your assigned key pair
$apikey = "your_public_key_string";

 

// You can use the same random string every time, but it would be more secure to generate it on the fly
$random = generate_guid();

 

// This is the "password" half of your assigned key pair
$privatekey = "your_private_key_string";

 

// This is the encrypted "digital signature" used by the API to authenticate you
// You may encrypt using an encryption algorithm you agree upon with us when you receive your key pair
$hash = encrypt($apikey + $ipaddress + $time + $random + $privatekey);

 

// Your request URL includes the $time, $random, and $hash values (but NEVER the $privatekey!) as parameters
$apiurl = "https://yourinstitution.campuslabs.com/engage/api/";
$resource = "organizations?";
$requesturl = $apiurl + $resource + "time=" + $time + _
     "&apikey=" + $apikey + "&random=" + $random + "&hash=" + $hash;

 

// Your request method type will be "GET" on most calls
$data = send_request("GET", $requesturl);

// End Pseudo Code

Encryption

Engage requires that you use an encryption algorithm for creating your digital signature or "hash" value. The type of algorithm you intend to use must be stated when you make your request for a public/private key pair.

IP Address Restriction

As a security tactic, Engage restricts access to your data by only allowing requests (which must first be authenticated using your key pair) that come from an IP address that you specify to be processed. Your hash should include the IP address however you should NOT need to include it as a parameter on your request URL.

Please note this security tactic can only be used with a single IP address; address ranges are not allowed.

Additional Security Options

Engage supports two additional security options that can assist you based on your specific situation.

Ignore IP Address Restriction

If you are unable to provide a static IP address for requests this security tactic can be ignored, however it is not recommended.  When using this option the IP address of your request server should not be included in the hash.  An HTTP 401 Unauthorized error will appear for requests containing an IP in the hash with this option.

This option must be configured by Campus Labs staff.

Data Access Restriction

When you request a key pair it can be granted access to all data available through the API, or only certain types of data. This is useful for situations where you only intend to pull certain types of information from the system. Please discuss this option with the Engage representative to whom you speak.

Further Information

If you are ready to look at what data can be retrieved through the API, please see the documentation on Working with Resources (Endpoints / Actions / Methods).

Troubleshooting your First Connection

Common gotcha's when first connecting to the API include:

  1. Ensuring that the requesting server’s time is synced to the US Naval Observatory Master Clock Network: http://tycho.usno.navy.mil/NTP/
  2. Confirming that the hash value is constructed in the correct order, the following must be included in the order listed:
  • the public key
  • the IP address of the server from which your code is run (skip when IP restriction has been disabled)
  • the current time
  • any random string such as a GUID
  • the private key

If you're still having trouble getting connected, contact the support team with a ticket and ask them to enable debug mode which will provide more verbose errors when making a simple connection to the /test call. Please include your public key in your request.

Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request

Contact Us