Authentication

Almost all requests to the API require proper authentication. There are a number of ways in which a client can authenticate, depending on the details and level of access available to it.

To summarise, a client can authenticate using any of the following methods

  •   Site API Key (and secret)
  •   User API Key (and secret)
  •   Session Token

In order to generate a Session token, a single call must be made with a valid Site or User credential. Session tokens are IP locked, and can be locked to an arbitrary IP (i.e. a Server can create on behalf of a client).

 

Site API Key

A Site API Key must be requested and cannot automatically be generated. Once enabled a site can create users, and users can authorise the site to authenticate on their behalf (they must do this through their 'home' site).

Any user created by a site will have that site set as their 'home', therefore sites creating users must implement a mechanism to allow users to authorise other site keys

to act on their behalf (A site may be a website, a smartphone app or anything similar).

When authenticating using a site key, three headers must be sent (unless creating a user, in which case the user key will not yet be known)

  •    X-VEHMAN-SITE
  •    X-VEHMAN-KEY
  •    X-VEHMAN-USER

The key used should be that of the site (not the user). If the Site is authorised to act on the users behalf, all transactions will be enacted as if that user had authenticated directly.

See the section 'Secret Keys' for information on how the key should be encoded.

 

User API Key

A user can authenticate directly against the API using their API key and Secret key, to do so the following HTTP headers should be included

  •    X-VEHMAN-USER
  •    X-VEHMAN-KEY

See the section 'Secret Keys' for information on how the key should be encoded.

 

Session Token

In order to allow the use of the API by client-side libraries (such as Javascript) without divulging API keys, a session token can be generated. The host system should place a call to /authentication/session using either their Site API key or the User API key.

The request should include the key "IP" with a value matching that of the client IP which will be making calls, as with all API calls this should be JSON encapsulated and submitted via POST within a variable 'data'.

In response, the API will create a unique, signed session token, locked to the specified IP. This session data can then be used to authenticate against the API for up to 15 minutes.

The Session token can be submitted in one of two ways

  •   HTTP Header X-VEHMAN-SESSION
  •   Request variable SESS (via POST or GET)

 

Secret Keys

Although it is expected that all API calls will take place over HTTPS, it's not mandated. As a result, authentication tokens are most at risk of compromise when in transit on-the-wire - they are encrypted within the API and MUST be encrypted when stored by client devices/sites.

To lessen the risk of compromise, Secret Keys should be used to sign requests in the form of an SHA1 hash. In order to ensure that a generated hash is not re-usable, the following method should be used

  1.   Generate the JSON request string and pass it through SHA1.
  2.   Prefix the secret key with the resulting string and pass through SHA1 once more
  3.   Submit the generated hash as the secret key.

To ensure that otherwise identical requests receive different hashes, it's strongly recommended that you include a random, arbitrary token within the JSON request string. Anything assigned to the key 'randtoken' will be ignored by the API except as part of validating the submitted hash.

 

Example Code

<?php
  $mykey='1234';
  $request = new stdClass();
  $request->redirect = true;
  $request->randtoken = mt_rand(0,1000000);
  $submission = json_encode($request);
  $api-secret = sha1(sha1($submission).$mykey);
  // Submit $api-secret as header X-VEHMAN-KEY

?>

 

API Responses

If authentication is successful, the requested action will be completed.

If authentication headers were not provided, or those that were provided were invalid, the API will return a HTTP 403. In most cases a JSON encapsulated response will also be provided detailing the issue encountered.