Authentication - API Keys

Owned by Victor Macko
Last updated: Feb 10, 2017

Setup your key

To access the API, an account must first be setup to act as the 'person' whom will access information and make changes to the system. This person must have the appropriate permissions for the actions they are carrying out on the system.

Each user which accesses the API will need an API Key generated for them - a user can have as many of these generated as required, and each can be revoked as required. Ideally, each application / system you intend to integrate should have it's own set of API keys generated which would in-turn be revoked at a later stage when they're no-longer required.

This means one key could be used for viewing event details on your public site, and another key for managing bookings and updating attendance records on another system or site.

The following values make up the api-key for each user.

  • Key
  • Secret

Setting up;

To setup an API key, goto the 'Permissions/password' page (from the tools menu when viewing their profile). If you would like to generate a new key for yourself, you can do-so via your 'My Account & Password' page, available within the 'Settings' menu on the left-hand side.

From there, an 'API Keys' button is at the top-right of the page which can be used to manage existing keys and generate new ones.


Permissions

The user assigned each API key must be given the appropriate permissions to the areas you require access to. This means that if you give access to only view certain event types, the system will not allow you to then roster people onto events as well - as the user does not have 'modify' access to any events.

As a rule of thumb, try to use a dedicated account with the most restrictive permissions possible, but still allow the user to perform whatever functions were required. This minimises the risk if the API keys were to fall into the wrong hands – eg. if your website is broken into, or your API keys were otherwise exposed.

Using your API keys

To use your API keys, all you need to do is include them in the request in the Authorisation header

If you're able to include them in the header specifically (eg. your software doesn't allow it), an alternate approach is to include them as follows in the URL;

https://<your key>:<your secret>@<yourcompany>.vtevents.com.au/....


Generating the authorisation header

The Authorisation header is constructed as follows:

  1. Username and password are combined into a string "username:password"
  2. The resulting string is then encoded using Base64 encoding
  3. The authorisation method and a space i.e. "Basic " is then put before the encoded string.

For example, if the user agent uses 'my username' as the username and 'my secret password' as the password then the header is formed as follows:

Authorization: Basic bXkgdXNlcm5hbWU6bXkgc2VjcmV0IHBhc3N3b3Jk

Example in PHP;

$encoded = "Authorization: Basic ".base64_encode($username.":".$password)