---

Authentication & Errors

We describe on this page the main features common to our API, including authentication and error reporting.

Authentication

Each API request is authenticated using HTTP Basic Auth, but as it is usually done over HTTPS, it will not reveal your password to anyone observing the packet stream. Provide your API token as the password. Your token is displayed on the api settings page (https://clara.io/settings/api).

Example Request

curl "https://clara.io/api/scenes" \
    -u username:c3be3060-fe81-467b-aa62-0ee42eea9c8b

Errors

The success or failure of an API request is indicated using an HTTP response code. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with the claro.io server.

HTTP Status Codes

401 - Unauthorized - User authentication failed. Your username or API token may be wrong.
403 - Forbidden
404 - Not found - The request resource does not exist.
422 - Unprocessable Entity
500 - Internal Server Error - The server encountered an unexpected condition which prevented it from fulfilling the request.

JSON Errors

The claro.io server will sometimes provide more detailed error information in JSON format. Often these JSON objects will have a message field and error stack field. However, both of these fields are optional. Return of information via custom attributes is also supported.

Example Response 1

HTTP 403 Forbidden

{
    message: 'No referral token',
    errors: [{field: 'referral', code: 'missing_field'}]
}

Example Response 2

HTTP 404 Not Found

{
    message: 'User not found',
    field: 'username'
}

Clara Node SDK

When using the Clara Node SDK:

To set authentication for subsequent requests:

$ clara set apiToken <api-token>
$ clara set username <username>

Alternatively, precede each api request on the same line with:

$ clara --apiToken <apiToken> --username <username> [request]

---