If you want to see real-life examples of how the API is being used, you can use your browsers' web dev tools to see what requests are being made when you use Voluum's front-end panel. It utilizes the very same API that is documented here, so you can inspect those requests to learn how they're being constructed.
-
-
Voluum exposes REST type API using secure HTTPS methods as a transport layer and JSON as a format.
Services
api.voluum.comOur centric API gateway is used to handle all requests to the relevant micro-services by the inclusion of distinct directory suffixes in URL.Example of directory suffixes:
To ensure resources for everyone, the API limits the number of requests a user may make per minute. The limit is not documented and is subject to change.
Identifiers
Certain requests also require a component identifier to be appended after a service directory, those of which are clearly indicated within our API documentation via curly brackets, for example:
Parameters
Additional parameters relevant to a service are then placed in the URL’s query string (after the question mark '?') to describe the requested data, for example:
...?from=2017-02-20T00:00:00Z&to=2017-02-21T00:00:00Z&tz=Etc/GMT -
-
-
-
Provided below is a breakdown of the different parts included within this example request URL:
-
-
-
cwauth-tokenAll authorized requests to the Voluum API must include a token sent in the HTTP header cwauth-token. This token authenticates and authorizes the caller to perform operations on the API.
Tokens are session-based, thus it is required to successfully create a session prior to executing any authorized requests. In order to obtain a token, the caller must send an HTTP POST request to the https://api.voluum.com/auth/session URL as described in the Security section of the Voluum API.
Request
Here’s a request example on how to create a session for demo account using curl:
curl -X POST \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Accept: application/json' \ -d '{"email":"voluumdemo@voluum.com","password":"1qaz!QAZ"}' \ 'https://api.voluum.com/auth/session'
Response
A response in JSON format is returned containing the authorization token along with the expiration timestamp for the session:
{ "token": "nmB8C_e8rcUXHnEix1ecoHMfCqX_rXdz", "expirationTimestamp": "2017-05-16T20:16:06.714Z", "inaugural": false }
Session tokens have an expiration period of 4 hours from the moment they are last used
Access keys
Should you want to automate your requests to the Voluum API, always use access keys instead of hard-coding your password into scripts. That way your password remains secret what is crucial for the account security. Moreover, the access keys have lower privileges and are blocked by some of the Voluum endpoints, thus your data is safe, even if the access key is stolen.
You can generate and revoke the access key in the Security settings of your Voluum account. The access key is always associated with the account that it is generated for. You can have more than one access key. We also recommend revoking and regenerating your access keys every month to minimize the account's exposure.
Access Key is generated per user. When using the Access Key from a worker account, you gain access to the same data that is available in that worker account's panel.
To find out how to generate the access key for your account, go to the Voluum knowledge base article.
Below you can find an example how to create a session with the generated access key:
curl -X POST \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Accept: application/json' \ -d '{"accessId": "c8493fe3-4dee-4171-b3fc-60645458f056", "accessKey": "V3HQ9RBihPx7mmw5QBRm7F0PBPSe8oHHQzLe"}' \ 'https://api.voluum.com/auth/access/session'
The following Voluum endpoints deny access for sessions created with an access key:
-
-
