Getting started

Authentication

Every request carries your API key. It identifies your user and defines what the response can include.

1In the control panel, open My Account › API and click Generate key. Give it a name that reminds you where the key will be used, such as “Monitoring”.
2Copy the key straight away: for security, it is shown only once. If you lose it, revoke it and generate a new one.
3Send the key in the X-API-Key header or as Authorization: Bearer.

Use the key only on your server. Never put it in web pages, apps or links: the API rejects keys sent in the URL. Each user can have up to 10 active keys and can revoke any of them in the same control panel tab.

Key format

The key starts with apk_, followed by 48 characters. In the control panel, each key is shown only by its beginning, the same value as the api_key.prefix field of /me.

Revoking and rotating keys

Revoking a key blocks requests made with it immediately. To replace a key without stopping your system, generate the new one, swap it in on your server and only then revoke the old one.

If your system only needs part of the data, create a user just for it in the control panel, with only the permissions it needs, and generate the key in that user's account.

What each user can see

RequestcURLPHPJavaScript

curl "https://api.on-cloud.live/v1/me" \
  -H "X-API-Key: $API_KEY"

<?php
$ch = curl_init('https://api.on-cloud.live/v1/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('API_KEY')],
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.on-cloud.live/v1/me', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data } = await res.json();

With the Authorization header

curl "https://api.on-cloud.live/v1/me" \
  -H "Authorization: Bearer $API_KEY"

Missing or revoked key401

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked."
  }
}