RotaCloud API

Authentication to the API is performed via HTTP Bearer Auth. You must provide an Authorization header in the format Bearer your-api-key-here. You can generate API keys from within your RotaCloud account. By default you will be authenticated as an anonymous user with administrative permissions. You can make calls on behalf of a specific user by providing a User header containing the ID of an active user within the account.

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error. Codes in the 5xx range indicate an error with our servers (these are rare).

Calls which fail will generally be accompanied by a human readable description of what went wrong. This will be included in an error property on the response.

In order to keep our servers happy, requests which return multiple items may be paginated. Paginated requests will include two extra response headers; X-Total-Count (the total number of results), and Link (containing one or more hypermedia link relations).

The possible values for the link relations are; next (the link relation for the immediate next page of results), last (the link relation for the last page of results), first (the link relation for the first page of results), and prev (the link relation for the immediate previous page of results).

You can optionally specify a limit URL parameter to change how many results are served per page (hard limits will apply), and you can navigate through paginated results using the offset URL parameter which lets you specify which result should be returned first, e.g. ?limit=10&offset=30 (this would return 10 results starting with record 30).

Calls to our API are limited on a per API key basis. The specific limit may vary. If you make too many calls in a given period the API will return a 429 response code.

A number of webhooks are available to configure for events that occur inside RotaCloud. Webhooks must be sent to a secure URL, and you can only have 1 webhook per event.

You can verify that the webhook has come from us by checking its signature which you will find in the RotaCloud-Signature request header. We generate signatures using a hash-based message authentication code (HMAC) with SHA-256. The process for verifying a request is as follows...

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. The value for the prefix ts corresponds to the timestamp, and v1 corresponds to the signature. You can discard all other elements.

Step 2: Prepare the payload for signing

The payload to sign is created by concatenating the timestamp (as a string), the character ., and the JSON request body. E.g. 123456789.[{"example":"event"}].

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the RotaCloud secret (found in your account) as the key, and use the payload you generated above as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.