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.

Authentication is handled transparently by the SDK, the params just need to be specified in the config options when instantiating the class 

$config = array(
  "api_key"  => "blahblahblah",
  "api_secret" => "blahblahblah"
);
$API = new WCEAAPI($config);

The api_key and api_secret params are madatory if you want to make any authenticated requests.

They can also be set after instantiating the class: 

$API = new WCEAAPI();
$API->setKey('blahblahblah');
$API->setSecret('blahblahblah');

The SDK then creates tokens and signs requests, as detailed on the left, automatically while making any request to the API.

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

$config = array(
  "api_key"  => "blahblahblah",
  "api_secret" => "blahblahblah"
);
$API = new WCEAAPI($config);
$API->addCustomHeader('Context-Id',123456);