API v1.1 Documentation

Authentication

You authenticate yourself to the WCEA API using you API key and Secret. Your API key can be exposed without worrying about security breaches, however always keep your API Secret in a safe place and never expose it anywhere.

To authenticate yourself successfully, you start off by getting these 3 components:

  1. The request timestamp, an RFC-2822 or ISO-8601 formatted representation of the current time
  2. The HTTP Verb, for example GET
  3. The request URI, for example: v1.1/user/1234

You join the above 3 components in that order, remove all spaces, and sign it using HMAC-SHA-256 algorithm, and your API secret as the encryption key. This is your Signature.

Now you are ready to make an authenticated request.

When you make your request, you have to send 3 important headers with the request

  1. Request-Time : The current time you used when you created your Signature.
  2. API-Key : Your API Key, NOT your API Secret.
  3. Signature : The Signature you generated earlier.

If all the above conditions are met, your request will be considered as authentic. If authentication fails, the API will reply with a 401 Unauthorized error.

Sandbox Mode

In sandbox mode, your API key and API secret remain the same. You should just direct your requests to http://sandbox.wceaapi.org instead of http://wceaapi.org.

Additional Portals

If your organization portal has additional portals, you authenticate using the same method as above using the same API Key and API Secret. However, you can switch context to the additional portal by adding a Context-Id header to the request. The value of Context-Id would be the ID of the additional portal.

See List all additional portals to get a list of all additional portals.

Example Authenticated Request

Making an authenticated GET request to v1.1/user/1234.

  1. Request Timestamp : Wed, 06 Nov 2013 16:32:03 +0000
  2. HTTP Verb : GET
  3. Request URI : v1.1/user/1234
  4. Your API Key : 5d41402abc4b2a76b9719d911017c592
  5. Your API Secret : 49f68a5c8493ec2c0bf489821c21fc3b

First you join the timestamp, verb and URI into a single string and remove all spaces, that gives you this token: Wed,06Nov201316:32:03+0000GETv1.1/user/1234

Then you sign the above token using HMAC-SHA-256, and your API Secret as the encryption key, that gives you this Signature: 42d8824f24fb50e6793aa111c889b7df4d 54bee9f5842a0d5fbca30cbfa469ae

Then you make the following authenticated request: 

curl -H "Request-Time: Wed, 06 Nov 2013 16:32:03 +0000" \
     -H "Api-Key: 5d41402abc4b2a76b9719d911017c592" \
     -H "Signature: 42d8824f24fb50e6793aa111c889b7df4d54bee9f5842a0d5fbca30cbfa469ae" \
     http://wceaapi.org/v1.1/user/1234

To make requests in the context of a micro-portal whose ID is 123456

curl -H "Request-Time: Wed, 06 Nov 2013 16:32:03 +0000" \
     -H "Api-Key: 5d41402abc4b2a76b9719d911017c592" \
     -H "Signature: 42d8824f24fb50e6793aa111c889b7df4d54bee9f5842a0d5fbca30cbfa469ae" \
     -H "Context-Id: 123456" \
     http://wceaapi.org/v1.1/user/1234