Getting started

What each user can see

A key sees exactly what its user sees in the control panel. There is nothing to configure in the API: the rules come from the user's organisations and permissions.

Only the user's organisations

The API only considers the organisations linked to the user, the same ones they can choose in the control panel.

Administrators see everything in the organisation

An administrator of the organisation, or of the main organisation, sees all of its TVs, files and playlists.

Everyone else depends on permissions

For other users, each organisation's permissions to view TVs, files and playlists apply — the same ones that unlock those pages in the control panel.

Changes apply straight away

A permission removed, an organisation removed or a user deactivated in the control panel already applies to the next request.

What is left out

Items from organisations without permission do not appear in lists. Requesting one of them directly returns 404, as if it did not exist.
In a playlist, a file the user cannot see comes with file set to null. The TVs of a playlist and the playlists of a file show only what the user can see.
Deleted items and TVs that have not been activated yet do not appear.

To find out what a key can read, call /organizations: each organisation comes with admin and permissions.

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.

RequestcURLPHPJavaScript

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

<?php
$ch = curl_init('https://api.on-cloud.live/v1/organizations');
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/organizations', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data } = await res.json();

Response200

{
  "data": [
    {
      "uid": "8f14e45fceea167a5a36dedd4bea2543",
      "name": "Loja Centro",
      "neutral_zone": false,
      "admin": true,
      "permissions": {
        "tvs": true,
        "files": true,
        "playlists": true
      }
    },
    {
      "uid": "1679091c5a880faf6fb5e6087eb1b2dc",
      "name": "Loja Shopping Norte",
      "neutral_zone": false,
      "admin": true,
      "permissions": {
        "tvs": true,
        "files": true,
        "playlists": true
      }
    }
  ]
}

Item from another organisation404

{
  "error": {
    "code": "not_found",
    "message": "Item not found or you do not have access to it."
  }
}