In order to use the various APIs a client must be authenticated. To authenticate the client must specify an API token in the field auth_token. For GET requests this should be a query string parameter, for POST/PUT/PATCH requests this should be a form field instead.

Currently only a simple token based authentication method is supported. In the future we might support more sophisticated methods such as OAth.

Note that the API is SSL only, plain HTTP is not enabled for security reasons.

Token Format

An authentication token is a string containing letters and numbers with a length of 32 characters. An example token looks like the following:

3e2afe6e7ec08db090c584aeed341abf

Tokens don’t contain any special characters that need to be encoded in URLs/form fields.

Authentication Errors

In case no or an invalid authentication token was specified an error message will be displayed in JSON. The structure of this message is as following:

{
    "error": "Reason for the error"
}

When such an error is displayed the HTTP status is set to “403 Forbidden”.

Example

Assuming there’s an API located at /foo that requires authentication you’d use it as following:

curl https://agora.olery.com/v2/foo?auth_token=XXX

Here XXX would be replaced by an actual authentication token.