User Authentication

User authentication refers to verifying a user’s identity--in this case, a user seeking access to the WizIQ Virtual Classroom API. This process ensures that only genuine requests reach the API, protecting users from attempts to fake their identities.

Once you arrange for an API-enabled premium plan, you’ll receive your Access Key and your Secret Key. These two keys are used during the authentication process.

When you perform a request with WizIQ Virtual Classroom API, you assemble the request, calculate the signature using your Secret Key, attach the signature to the request, and send it to WizIQ Virtual Classroom API. WizIQ Virtual Classroom API verifies the signature of the request and, if authenticated, processes the request.

The WizIQ Virtual Classroom API user authentication process

The WizIQ Virtual Classroom API user authentication process looks like this:

As you can see, your site:

  • Prepares your method request.
  • Calculates the HMAC authentication signature using your Access Key and your Secret Key.
  • Sends the request to the WizIQ servers.

When the WizIQ servers receive your request, they:

  • Use the included Access Key to look up your Secret Key.
  • Calculate the HMAC authentication signature using your Access Key and your Secret Key.
  • Respond to a correct signature by processing your request, or respond to an incorrect signature by returning an error.

Now let’s look at each of these elements in more detail.

Note: You don’t need to write your own authentication code! See the SDK download page for Java, .NET, PHP, and RubyOnRails libraries that handle WizIQ Virtual Classroom authentication and more.

WizIQ Virtual Classroom API authentication building blocks

In order for the WizIQ Virtual Classroom API to authenticate a method request from your site, three pieces of information must be included: your access key, your security signature, and a timestamp stating when the request was created. The SDK contains libraries that handle this process for you, but we’ve included the details below so you have a better understanding of what’s happening.

WizIQ Virtual Classroom API authentication: Access Key

Every WizIQ Virtual Classroom-enabled account has a unique Access Key. This key looks similar to the following:

022QF06E7MXBSH9DHM02

Your Access Key must be included with every WizIQ Virtual Classroom API request.

WizIQ Virtual Classroom API authentication: Secret Key
Every WizIQ Virtual Classroom-enabled account has a unique Secret Key. This key will look similar to the following:

kWcrlUX5JEDGM/LtmEENI/aVmYvHNif5zB+d9+ct

Never include the Secret Key, by itself, with a WizIQ Virtual Classroom API request. If your Secret Key becomes compromised (publicly visible or copied for someone else’s use), contact WizIQ support immediately.

WizIQ Virtual Classroom API authentication: Timestamp
Each request through the WizIQ Virtual Classroom API must contain the date and time it was created. Through the API, this value is represented in epoch time, calculated from the time the message was created in Coordinated Universal Time (UTC). Epoch time is the number of seconds between midnight on January 1, 1970 in GMT/UTC and the time you’re referring to.

Note: For the purposes of the WizIQ Virtual Classroom API, UTC and Greenwich Mean Time (GMT) are considered equivalent.

So for a request created at Mon, 20 Jun 2011 02:17:06 GMT/UTC, its epoch time would be as follows:

1308536226

Note: If you’re not familiar with epoch time, the Epoch Converter is an excellent resource, with interactive calculators and code examples for many different languages.

WizIQ Virtual Classroom API authentication: Signature

Calculating the WizIQ Virtual Classroom API authentication signature involves making a HMAC-SHA1 hash of the API request parameters:

For the purpose of these calculations, if there are any URLs in the message, some characters must be converted to their hex codes before hashing to prevent errors. These two characters are the plus (+) and the forward slash (/). Instead of using these literally in URLs, the SDK libraries replace all pluses in your URLs with %2B, and all forward slashes with %2F.

For example:

status_ping_URL="http://www.example.com/Linux+StudyGuide"

would need to be converted to the following before you calculate your hash:

status_ping_URL="http:%2F%2Fwww.example.com%2FLinux%2BStudyGuide"

Once you have the hash, create the Base64-encoded signature using the Secret Key. Doing so gives you an ASCII string you can attach to your request. When WizIQ receives the request, it will then decode the string to authenticate that the request came from you.

See the complete list of API methods in WizIQ Virtual Classroom API documentation

For enquiries: Call us at +1-919-647-4727 -or- Contact us

© 2017 WizIQ Inc. All rights reserved.