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.