REST autentizace (CZ)

Vytvořte API klíč se scope vcp:read a volejte /api/v1/vcp/sites/* s hlavičkou X-API-Key.

API klíč posílejte v hlavičce X-API-Key při každém volání na https://api.voke.turena.cz/api/v1/vcp/sites/*. Tato hlavička je jediné, podle čeho REST API ověřuje volajícího.

Pro scopes, hashování, použití přes AMQP a rotaci viz API keys & auth.

Předpoklady

Účet ORG_ADMIN v cílové organizaci.
REST klient schopný nastavit vlastní hlavičky requestu — curl, HTTPie, Postman, nebo vlastní SDK.

Krok 1 — Otevřete stránku Connections

Přihlaste se na https://voke.turena.cz, zvolte správnou organizaci a otevřete Workspace settings → Connections (/orgs/<orgId>/settings/connections).

Connections Overview tab with the Connect partner button highlighted

Klikněte na + Connect partner pro otevření průvodce.

Krok 2 — Vyberte preset

Průvodce nabízí pět presetů. Jakýkoliv preset, který obsahuje vcp:read, vám umožní volat REST API — vyberte ten, který odpovídá tomu, co integrujete.

Connect partner wizard, Use case step with five preset radios

Preset	Vhodné pro	REST přístup
Trading platform partner	Plná ESM integrace: odesílání příkazů, příjem telemetrie, posílání rozvrhů a režimů.	Ano (plná sada `vcp:*`)
Telemetry consumer (read-only)	Analytické nebo monitorovací služby, které konzumují živý AMQP telemetrický stream a zároveň potřebují REST snapshoty.	Ano
HTTP read-only	Dashboardy, reporty a skripty, které potřebují jen REST. Pouze REST snapshoty — žádný AMQP connect scope.	Ano (jediný scope na klíči)
Internal tool	Interní skripty proti non-VCP admin REST endpointům.	Ne
Custom	Vyberte scopes ručně.	Volitelně

Krok 3 — Ověřte, že je vcp:read zaškrtnutý

REST endpointy vyžadují scope vcp:read. Trading platform partner, Telemetry consumer i HTTP read-only ho přednastaví jako zaškrtnutý; ostatní presety ne. Před pokračováním se ujistěte, že je zaškrtnutý. Ostatní scopes na REST nemají vliv — nechte je tak, jak je nastavil váš preset.

Permissions step with all seven scope cards visible

Scope	Co umožňuje
`vcp:connect`	Otevřít AMQP připojení. Pro REST není potřeba.
`vcp:read`	Každý endpoint pod `/api/v1/vcp/sites/*` — seznam lokalit, konfigurace lokality, telemetrie, odečty elektroměru, rozvrhy, historie příkazů.
`vcp:write:setpoint`	Publikovat setpoint příkazy přes AMQP.
`vcp:write:device-command`	Publikovat příkazy na úrovni zařízení přes AMQP.
`vcp:write:schedule`	Publikovat day-ahead rozvrhy přes AMQP.
`vcp:write:mode`	Publikovat změny provozního režimu přes AMQP.
`vcp:write:config`	Posílat konfiguraci lokality přes AMQP.

Krok 4 — Pojmenujte klíč a vygenerujte ho

Dejte klíči název, který později poznáte, a partner ID. Pokud má vaše služba stabilní egress IP, přidejte ji do allowlistu. Voke pak odmítne volání z jakékoliv jiné adresy.

Connect partner wizard, Network step with name and partner ID filled in

Klikněte na Generate. Voke na další obrazovce zobrazí plaintext klíč jednou.

Klíč se zobrazí přesně jednou. Zkopírujte ho do svého správce tajemství dříve, než opustíte obrazovku s odhalením klíče. Pokud ho ztratíte, vytvořte nový klíč se stejnými scopes a starý zrušte.

Krok 5 — Pošlete svůj první autentizovaný request

Nastavte klíč jako X-API-Key a zavolejte libovolný endpoint /vcp/sites/*. REST base URL je https://api.voke.turena.cz/api/v1/vcp/sites.

Záložka Quickstart na stránce Connections přednastaví tyto snippety s vaším org slugem. Nahraďte <your-key> hodnotou z obrazovky s odhalením klíče.

Quickstart tab with a curl example sending X-API-Key

curl -H "X-API-Key: voke_a1b2c3..." \
  "https://api.voke.turena.cz/api/v1/vcp/sites/<plant-uuid>/config"

const res = await fetch(
  `https://api.voke.turena.cz/api/v1/vcp/sites/${plantUuid}/config`,
  { headers: { 'X-API-Key': process.env.VOKE_API_KEY! } },
);
if (!res.ok) throw new Error(`Voke REST ${res.status}: ${await res.text()}`);
const config = await res.json();

Úspěšné volání vrátí envelope s konfigurací lokality:

{
  "siteId": "00000000-0000-4000-a000-000000000123",
  "constraints": {/* ... */},
  "fallback": {/* ... */},
  "operatingMode": "...",
  "modeOverride": null,
  "activeSchedule": null,
  "pendingCommands": [/* ... */]
}

Chyby

Status	`code`	Příčina
`401 Unauthorized`	`UNAUTHORIZED`	Chybí hlavička `X-API-Key`, nebo byl klíč zrušen, vypršel, či je neznámý. Přihlášená admin browser session se nepočítá — REST volání ověřuje pouze hlavička.
`401 Unauthorized`	`UNAUTHORIZED`	IP volajícího je mimo nakonfigurovaný allowlist (zpráva `IP not allowed`).
`403 Forbidden`	`FORBIDDEN`	Klíč se ověřil, ale chybí mu `vcp:read`. Vytvořte nový se správným scope.
`404 Not Found`	`SITE_NOT_FOUND`	Site UUID patří jiné organizaci. Voke vrací 404 (ne 403), aby nikdy neprozradil existenci.

Pro kompletní error envelope a sémantiku retry viz Errors & retries.

Další kroky

REST Reference — interaktivní Scalar reference pro každý endpoint /vcp/sites/*.
API keys & auth — rotace, revokace, model uložení a enum ApiKeyScope.
Errors & retries — error envelope, idempotence a backoff.

REST autentizace (CZ)

On this page