Overview

The Engage API was designed to be straightforward to use while providing an appropriate measure of security. This model relies on secure HTTP (HTTPS) and public key cryptography, or a public and private key pair. Both a valid digital signature (a hash value) and a time value accurate to within thirty seconds of the current international time 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 private key for your API public key is never openly transmitted, thus minimizing the potential for a security breach.
  • Request expirations ensure that all requests made to the API will only be processed if they occur within thirty 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 them, the API would not be able to process such requests.
  • 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, but instead uses a key pair, made up of a public key and a private key. Institutions using the API must also include a number of specific pieces of information when making a request, so that the API can verify the authenticity of that 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. For example, 7/27/2013 9:02:00 would be sent as 1374930120000.
  2. A valid public key
  3. A random string, such as a GUID
  4. A digital signature, or hash value, consisting of the following values in the listed order:
  • the public key
  • the current time
  • any random string such as a GUID
  • the private key

If your key pair has been configured with an IP Address Restriction, so that only requests from a specific IP Address will be honored, your hash will instead follow this format: 

  • the public key
  • the IP address of the system from which the request is made
  • the current time
  • any random string such as a GUID
  • the private key

 Supported hash functions

The following cryptographic hash functions are supported: 

  • MD5
  • SHA-256
  • SHA-384
  • SHA-512

The items above should be added as parameters on the request URL. 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
$now = time()
$time = convert_to_milliseconds($now)

// Get IP Address, if needed
$ipaddress = get_server_ip()

// Public key value
$apikey = "your_public_key_string"

// Generate a random value
$random = generate_guid()

// Private key value
$privatekey = "your_private_key_string"

// Encrypt your digital signature
$hash = encrypt($apikey + $ipaddress + $time + $random + $privatekey)

// Build your request URL
$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. The type of algorithm you intend to use must be stated when you make your request for a public/private key pair.

Additional Security Options

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

IP Address Restriction

For security purposes, Engage restricts access to your data by only allowing requests from an IP address that you specify. When enabled, your hash should include the IP address. You do NOT need to include it as a parameter on your request URL.

This option can only be used with a single IP address; address ranges are not accepted.

If you are unable to provide a static IP address for requests, or if your requests should be accessible from any location, this option can be disabled. 

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 your Engage representative.

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 errors that can occur when connecting to the API include:

  1. The requesting server's time does not match internet time. 
  2. The pre-hash value is constructed in the correct order; see above for details.
  3. IP Address was included in hash when IP address restriction was disabled.
  4. IP Address was not included when IP address restriction was enabled.
  5. IP Address is incorrect.

If you're still having trouble getting connected, contact the support team with details of your request and the response you have received. We can then troubleshoot the connection further.

Have more questions? Submit a request