API — bevezetés és hitelesítés

A SignalGuard teljes funkcionalitása elérhető REST API-n keresztül a https://api.signalguard.hu címen. Ugyanazok a műveletek MCP-n keresztül is hívhatók — a kettő mögött azonos műveleti réteg áll.

Kulcs igénylése

Két út van:

1. Admin felületen (ajánlott): Rendszer → API/MCP kulcsok → Új kulcs — a kulcs a jelszavad megadása után jön létre, és csak egyszer látható.
2. API-hívással: POST /auth/keys a szerver-tokennel és a belépési adatokkal:

curl https://api.signalguard.hu/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"server_token":"sgt_...","email":"...","password":"...","name":"automatizáció"}'

A válaszban kapott sga1... kulcs a te jogosultságaiddal működik, és az admin felületen bármikor visszavonható. A visszavont kulccsal indított kérések elutasításra kerülnek.

Hitelesítés

Minden /v1/... kéréshez Authorization fejléc kell:

curl https://api.signalguard.hu/v1/organisations \
  -H "Authorization: Bearer sga1...."

Útvonalak

A végpont-referencia minden műveletet a megszokott erőforrás-útvonalán mutat (pl. GET /v1/devices, DELETE /v1/devices/123) — ez a futó rendszer /v1/openapi.json leírásából generálódik.

Emellett minden művelet elérhető egy egységes műveleti alakban is: POST /v1/ops/<művelet_neve> JSON-törzzsel (olvasó műveleteknél GET is, query-paraméterekkel). A művelet neve megegyezik az azonos nevű MCP toollal — ez az alak gépi hívóknak és az MCP-vel párhuzamos használathoz kényelmes. A kettő teljesen egyenértékű: ugyanaz a kód fut, ugyanazzal a validációval és naplózással.

Válasz- és hibaformátum

Minden válasz egységes borítékban érkezik:

{ "ok": true, "result": ... }
{ "ok": false, "code": "unauthorized", "message": "Hiányzó bearer kulcs." }

A HTTP-státusz a hiba jellegét követi (400 érvénytelen input, 401 hitelesítési hiba, 404 nem található, 409 ütközés, 429 rate limit).

A dry_run elv

Minden destruktív művelet (törlések, archivált riasztások ürítése, típusváltási szinkron) elfogad dry_run: true paramétert: ilyenkor semmit nem módosít, csak az érintett elemek darabszámait adja vissza. Érdemes minden törlést egy dry_run-nal kezdeni:

{ "device_id": 123, "dry_run": true }
→ { "ok": true, "result": { "dry_run": true, "sensors": 4, "incidents": 12, "values": 2, "rule_refs": 3 } }

Ha egy törlést más adat blokkol (pl. a helyszínen még eszközök vannak), a művelet hibát ad a blokkoló elemek darabszámával — sosem kaszkádol némán.

Korlátok

• A kulcs-kiadó és belépési végpontok IP-nkénti rate limitet kapnak.
• Minden hívás auditnaplóba kerül (művelet, csatorna, eredmény); a napló 90 napig őrződik.