API Reference — přehled

Base URL

http://localhost:3001/api     # lokální vývoj
https://api.atrea.eu/api      # produkce

Všechny endpointy jsou pod prefixem /api.

Autentizace

JWT Bearer token

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Interní API klíč (service-to-service)

x-internal-api-key: <hodnota z config.internalApiKey>

Bez autentizace

Endpointy /check, /test, /version a /docs nepotřebují žádný token.

---

Formát odpovědi

Všechny odpovědi mají konzistentní strukturu:

Úspěch

{
  "success": true,
  "data": { ... }
}

Chyba

{
  "success": false,
  "error": "Popis chyby",
  "code": "PERMISSION_DENIED",
  "details": { ... }
}

Seznam

{
  "success": true,
  "data": [ ... ]
}

---

HTTP stavové kódy

Kód	Popis	Kdy
200	OK	Úspěšný GET, PUT
201	Created	Úspěšný POST (vytvoření)
204	No Content	Úspěšný DELETE
400	Bad Request	Chybná validace body
401	Unauthorized	Chybí nebo neplatný token/API klíč
403	Forbidden	Nedostatečná oprávnění
404	Not Found	Zdroj neexistuje
409	Conflict	Duplicitní záznam (unique constraint)
422	Unprocessable Entity	Validační chyba
500	Internal Server Error	Neočekávaná chyba serveru

---

Přehled endpointů

Ověřování oprávnění (/check)

Metoda	Endpoint	Auth	Popis
POST	/check	volitelně	Ověření jednoho oprávnění
POST	/check/bulk	volitelně	Ověření více oprávnění najednou
POST	/check/effective	volitelně	Všechna efektivní oprávnění
POST	/check/cache/clear	—	Vyčistit permission cache

Uživatelé (/users)

Metoda	Endpoint	Auth	Popis
GET	/users	JWT + AppAdmin	Seznam uživatelů
POST	/users	JWT + AppAdmin	Vytvoření uživatele
GET	/users/:email	JWT + AppAdmin	Detail uživatele
PATCH	/users/:email/active	JWT + SuperAdmin	Aktivace/deaktivace
GET	/users/:email/apps/:appCode/roles	JWT + AppAdmin	Role v aplikaci
PUT	/users/:email/apps/:appCode/roles	JWT + AppAdmin	Nastavení rolí
GET	/users/:email/apps/:appCode/resources/:type/:id/permissions	JWT + AppAdmin	Resource overrides
PUT	/users/:email/apps/:appCode/resources/:type/:id/permissions	JWT + AppAdmin	Nastavení overrides
GET	/users/admins/apps/:appCode	JWT	Seznam app adminů
POST	/users/admins/apps/:appCode	JWT + SuperAdmin	Přidání app admina
DELETE	/users/admins/apps/:appCode/:email	JWT + SuperAdmin	Odebrání app admina
GET	/users/superadmins/list	JWT + SuperAdmin	Seznam superadminů
POST	/users/superadmins	JWT + SuperAdmin	Přidání superadmina
DELETE	/users/superadmins/:email	JWT + SuperAdmin	Odebrání superadmina

Profil (/profile)

Metoda	Endpoint	Auth	Popis
GET	/profile/me	JWT	Vlastní profil
PUT	/profile/me	JWT	Aktualizace profilu
GET	/profile/me/admin-status	JWT	Admin status
GET	/profile/me/apps	JWT	Všechny per-app preference
GET	/profile/me/apps/:appCode	JWT	Per-app preference
PUT	/profile/me/apps/:appCode	JWT	Aktualizace preference
GET	/profile/me/notifications/:appCode	JWT	Notifikační preference
PUT	/profile/me/notifications/preferences/bulk	JWT	Bulk update notifikací
PUT	/profile/me/notifications/preferences/:typeId	JWT	Update jednoho typu
GET	/profile/me/push/vapid-key	JWT	VAPID public key
POST	/profile/me/push/subscribe	JWT	Registrace push subscripce
POST	/profile/me/push/unsubscribe	JWT	Odregistrování subscripce
GET	/profile/me/push/subscriptions	JWT	Seznam subscripcí
GET	/profile/:email	JWT + AppAdmin	Profil jiného uživatele

Aplikace (/applications)

Metoda	Endpoint	Auth	Popis
GET	/applications	JWT + SuperAdmin	Seznam aplikací
GET	/applications/:appCode	JWT + SuperAdmin	Detail aplikace
POST	/applications	JWT + SuperAdmin	Vytvoření aplikace
PUT	/applications/:appCode	JWT + SuperAdmin	Aktualizace aplikace
DELETE	/applications/:appCode	JWT + SuperAdmin	Smazání aplikace

Oprávnění & Role

Metoda	Endpoint	Auth	Popis
GET	/applications/:appCode/permissions	JWT + AppAdmin	Seznam oprávnění
POST	/applications/:appCode/permissions	JWT + AppAdmin	Vytvoření oprávnění
PUT	/applications/:appCode/permissions/:id	JWT + AppAdmin	Aktualizace oprávnění
DELETE	/applications/:appCode/permissions/:id	JWT + AppAdmin	Smazání oprávnění
GET	/applications/:appCode/roles	JWT + AppAdmin	Seznam rolí
GET	/applications/:appCode/roles/:id	JWT + AppAdmin	Detail role
POST	/applications/:appCode/roles	JWT + AppAdmin	Vytvoření role
PUT	/applications/:appCode/roles/:id	JWT + AppAdmin	Aktualizace role
DELETE	/applications/:appCode/roles/:id	JWT + AppAdmin	Smazání role
PUT	/applications/:appCode/roles/:id/permissions	JWT + AppAdmin	Nastavení oprávnění role

Notifikace (/internal)

Metoda	Endpoint	Auth	Popis
POST	/internal/notifications	x-internal-api-key	Odeslání notifikace
POST	/internal/notifications/bulk	x-internal-api-key	Hromadné odeslání
GET	/internal/notifications/types	x-internal-api-key	Typy notifikací
GET	/internal/notifications/log/:email	x-internal-api-key	Log příjemce
GET	/internal/notifications/log/app/:appCode	x-internal-api-key	Log aplikace
GET/POST/PUT/DELETE	/internal/notifications/templates/*	x-internal-api-key	Šablony

Admin (/admin)

Metoda	Endpoint	Auth	Popis
GET	/admin/dashboard/stats	JWT + Admin	Dashboard statistiky
GET/POST/PUT/DELETE	/admin/notifications/types/*	JWT + SuperAdmin	Typy notifikací
GET/POST/PUT/DELETE	/admin/notifications/templates/*	JWT + SuperAdmin	Šablony
POST	/admin/notifications/templates/preview	JWT + SuperAdmin	Preview šablony
GET	/admin/notifications/log/:appCode	JWT + SuperAdmin	Log notifikací
GET/POST/PUT/DELETE	/admin/brands/*	JWT + SuperAdmin	Správa brandů

Zitadel (/zitadel)

Metoda	Endpoint	Auth	Popis
POST	/zitadel/webhook	x-webhook-secret	Webhook od Zitadelu
GET	/zitadel/health	—	Dostupnost Zitadelu
GET	/zitadel/discovery	—	OIDC discovery
GET	/zitadel/login	—	Start OIDC login
GET	/zitadel/callback	—	OIDC callback
GET	/zitadel/admin/orgs	JWT + SuperAdmin	Seznam organizací
POST	/zitadel/admin/orgs	JWT + SuperAdmin	Vytvoření organizace
PUT	/zitadel/admin/orgs/:orgId/branding	JWT + SuperAdmin	Branding organizace
POST	/zitadel/admin/orgs/:orgId/setup	JWT + SuperAdmin	Full brand setup

---

Interaktivní dokumentace

Pro testování endpointů přímo v prohlížeči použijte Swagger UI.

Swagger UI nabízí:

• Popis každého parametru a těla requestu
• Možnost autentizace JWT tokenem
• Přímé testování API volání
• JSON schémata request/response