API Concepts

Follow

The Emtrain Learning Management System stores, launches, and tracks a variety of training (eLearning, Workshops, Webinars, etc.) created and taken by individuals in an organization. The Emtrain LMS API provides access to a variety of LMS functions and data.

Accessing the API

API calls are made over an https connection by sending either GET or POST requests.

The base URL for the API is:

https://lms2.emtrain.com/lms/api/ 

Each API method has a corresponding .php file which handles calls to that method. Generally, the name of the .php file which handles calls for a method is named after the method itself. For example, the learner_sign_in API method URL is:

https://lms2.emtrain.com/lms/api/learner_sign_in.php 

All url parameters must be url-encoded in accordance with RFC 3986.

Authentication

To access API methods which require authentication you will need an API Key and an API Secret. Your company’s API Key and Secret can be obtained by signing into Emtrain as an administrator and clicking on the “Developer Integration” link under the “My Account” section on the LMS Dashboard Homepage. If this link is not available on your admin dashboard menu, please contact customer support to obtain your API key and secret.

API Keys identify the LMS account for which an API call is being made. API Keys are included as a parameter in calls to API methods and as such are (technically) visible to the public. API Keys do not require safe-guarding.

API Secrets are used in the generation of an authenticated call signature parameter (auth_sig) for calls to API methods which require authentication. Likewise, when callbacks are supplied as parameters to an API method the callback http(s) request from Emtrain will contain an authenticated call signature generated using your account’s API Secret. API Secrets should only be known by the Emtrain LMS system and the software your API calls are originating from. API Secrets should be safe-guarded.

To help prevent API call re-play, API methods requiring authentication will require an auth_time parameter. The auth_time parameter should be set to the number of seconds since January 1, 1970 00:00:00 GMT (Unix epoch). Calls to API methods requiring authentication which are older than 1 hour will be rejected.

Methods to Generate an Authentication Signature Call to API:

  1. Order all method parameter key-value pairs based on the ASCII value of the key (i.e. ascending alpha-numeric order).
  2. Create a canonical string by concatenating (in-order) all key-value pairs, placing a "=" character between each key and its value, and placing a "&" character between each key-value pair.
  3. Salt your canonical string with your API Secret by appending your API Secret to the end of the string.
  4. Create an authenticated call signature by generating a SHA1 hash (raw output) from your salted canonical string.
  5. Base64 encode your authenticated call signature hash. Add this Base64 encoded value to your call parameters as auth_sig.
  • Be sure to include the auth_time parameter when ordering your key-value pairs and generating your canonical string.
  • All strings should be UTF-8 encoded.
  • All url parameters must be url-encoded in accordance with RFC 3986.

 

Example of Authentication Signature Generation:

Assuming we want to call the learner_sign_in API method, the authentication signature generation procedure is as follows:

Assume we are working with the following data:

api_key = "16e2d5e3-7271-41f2-b90c-c11098f07515"

 

api_secret = "4b751f18-62e7-4d0b-9099-b1e42f9191da"
auth_time = "1324579885"
learner_id = "674567"

The required parameters for the learner_sign_in API method are (in no particular order): learner_id, api_key, auth_time, and (of course) the auth_sig we are generating.

To generate our auth_sig first we will create a canonical string by ordering alpha-numerically (based on key) each key-value pair. We will place a "=" character between each key and its value and we will place a "&" character between each key-value pair. Following this procedure will result in:

canonical_string = "api_key=16e2d5e3-7271-41f2-b90c-c11098f07515&auth_time=1324579885&learner_id=674567" 

Next, we will salt our canonical_string by appending our api_secret to the end of the string. Doing so will result in:

salted_canonical_string = "api_key=16e2d5e3-7271-41f2-b90c-c11098f07515&auth_time=1324579885&learner_id=6745674b751f18-62e7- 4d0b-9099-b1e42f9191da" 

Finally, we will generate a SHA1 hash from our salted_canonical_string and Base64 encode the raw hash output. This Base64 encoded value is our finalized auth_sig:

auth_sig = "re6Y+/TevucNkNycK5tb+WwHUm4=" 

...after url-encoding...

auth_sig = "re6Y%2B%2FTevucNkNycK5tb%2BWwHUm4%3D" 

 

Required Authentication Parameters

Parameter: page5image17448api_key
Required: Yes
Description: Your API Key
Example: "16e2d5e3-7271-41f2-b90c-c11098f07515"
Parameter: page5image17448auth_time
Required: Yes
Description: The number of seconds since January 1, 1970 00:00:00 GMT (Unix epoch).
Example: "1324579885"
Parameter: page5image17448auth_sig
Required: Yes
Description: Base64 encoded SHA-1 hash of call parameters, salted with your API Secret. (see Generating an authentication signature...)
Example: "re6Y+/TevucNkNycK5tb+WwHUm4="

Comments