Aplikace (`/applications`)

Správa aplikací v systému. Pouze SuperAdmin může vytvářet, upravovat a mazat aplikace.

GET `/applications` — seznam aplikací

http

GET /api/applications
Authorization: Bearer <superadmin-token>

Response

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "crm",
      "name": "CRM Systém",
      "description": "Správa zákazníků a obchodních příležitostí",
      "createdAt": "2024-01-10T08:00:00.000Z"
    },
    {
      "id": 2,
      "code": "vallox-panel",
      "name": "Vallox Panel",
      "description": null,
      "createdAt": "2024-01-11T09:00:00.000Z"
    }
  ]
}

GET `/applications/:appCode` — detail aplikace

http

GET /api/applications/crm
Authorization: Bearer <superadmin-token>

Response

json

{
  "success": true,
  "data": {
    "id": 1,
    "code": "crm",
    "name": "CRM Systém",
    "description": "Správa zákazníků a obchodních příležitostí",
    "createdAt": "2024-01-10T08:00:00.000Z"
  }
}

POST `/applications` — vytvoření aplikace

http

POST /api/applications
Authorization: Bearer <superadmin-token>
Content-Type: application/json

Request body

json

{
  "code": "nova-app",
  "name": "Nová Aplikace",
  "description": "Popis aplikace (volitelné)",
  "supportedLanguages": ["cs", "en"]
}

Pole	Typ	Povinné	Popis
`code`	string	✓	Unikátní kód aplikace (slug)
`name`	string	✓	Zobrazované jméno
`description`	string	✗	Volitelný popis
`supportedLanguages`	string[]	✗	Podmnožina jazyků, které aplikace umí (kódy malými písmeny). Každý kód musí existovat v registru jazyků (`/admin/languages`) — jinak `400` s `details.code = "UNKNOWN_LANGUAGES"`. Prázdné pole `[]` = bez omezení. Vrací se ve všech `GET /applications*`.

Konvence pojmenování

code by měl být lowercase slug bez mezer: crm, vallox-panel, atrea-service.

Response `201 Created`

json

{
  "success": true,
  "data": {
    "id": 3,
    "code": "nova-app",
    "name": "Nová Aplikace",
    "description": "Popis aplikace",
    "createdAt": "2024-01-20T12:00:00.000Z"
  }
}

PUT `/applications/:appCode` — aktualizace aplikace

http

PUT /api/applications/nova-app
Authorization: Bearer <superadmin-token>
Content-Type: application/json

Request body

json

{
  "name": "Nová Aplikace v2",
  "description": "Aktualizovaný popis",
  "supportedLanguages": ["cs", "en", "de"]
}

code nelze měnit po vytvoření. supportedLanguages se při poslání celé přepíše (není to patch jednotlivých prvků).

DELETE `/applications/:appCode` — smazání aplikace

http

DELETE /api/applications/nova-app
Authorization: Bearer <superadmin-token>

Response `204 No Content`

Kaskádové smazání

Smazání aplikace smaže kaskádově všechna závislá data:

Všechna oprávnění aplikace
Všechny role aplikace
Všechna přiřazení rolí uživatelům
Všechny resource-level overrides
Všechny app adminy
Notifikační typy a šablony

Katalog entit aplikace

Každá aplikace si v admin panelu definuje typy entit, na které lze omezit oprávnění. Například project, unit nebo customer. Data těchto entit zůstávají ve zdrojové aplikaci; user-api ukládá pouze typ a konkrétní ID použité v přiřazení oprávnění.

http

GET    /api/applications/kgb/entities
POST   /api/applications/kgb/entities
PUT    /api/applications/kgb/entities/12
DELETE /api/applications/kgb/entities/12

json

{
  "code": "project",
  "name": "Projekt",
  "description": "Projekt v KGB",
  "idLabel": "Číslo projektu",
  "listEndpoint": "https://api.kgb.example.com/api/projects"
}

code je technický klíč používaný jako resourceType; idLabel říká panelu, jak pojmenovat vstup konkrétního resourceId. Jakmile má aplikace v katalogu alespoň jednu entitu, API u nových přiřazení odmítne neznámý resourceType. Použitou entitu nelze smazat ani přejmenovat, dokud existují její přiřazení.

Seznam konkrétních entit

listEndpoint je volitelná absolutní URL (http/https, bez přihlašovacích údajů v URL) na endpoint aplikace, který vrací existující entity daného typu. Panel si je nechá načíst přes user-api a nabídne je jako výběr místo ručního opisování ID:

http

GET /api/applications/kgb/entities/project/items

json

{
  "entityCode": "project",
  "endpoint": "https://api.kgb.example.com/api/projects",
  "items": [
    { "id": "42", "label": "Rekonstrukce ZŠ Kladno", "description": "Kladno" }
  ]
}

user-api volá endpoint serverově (cílová aplikace tedy nemusí řešit CORS) a přeposílá Authorization hlavičku přihlášeného administrátora — aplikace si tak sama rozhodne, co vrátí. Odpověď stačí ve tvaru pole [{ id, name }]; rozpozná se i obálka (data, items, results, …), pole id/code/uuid jako identifikátor a name/title/label jako popisek. Nedostupný endpoint vrací 502 a panel nechá ID zadat ručně.

Omezení správy panelu na jednu aplikaci

Admin panel je sám aplikace auth. V jejím katalogu existuje entita application, jejíž resourceId je kód spravované aplikace. Právo applications.manage je neglobální, takže lze udělit například jen:

text

uživatel: kolega@firma.cz
panelová aplikace: auth
entita: application
ID entity: kgb
právo: applications.manage = čtení | zápis | bez oprávnění

Uživatel zároveň potřebuje roli application_manager. Ta umožní vstup do panelu, ale sama nezpřístupní žádnou aplikaci. Pro každou aplikaci se samostatně nastaví právě jedna z těchto úrovní:

Čtení (view) — detail aplikace a všechna související data lze zobrazit, ale nelze je měnit.
Zápis (edit) — lze zobrazit i upravovat vše patřící k aplikaci.
Bez oprávnění — aplikace se uživateli nezobrazí a její endpointy vrací 403 Forbidden.

Pro další aplikaci se přidá další entity grant. Globální panel_admin nadále spravuje všechny aplikace.

Úroveň platí pro celý strom dané aplikace: detail a konfiguraci, brandy a instance/callbacky, ZITADEL synchronizaci, katalog entit, role a oprávnění, správce aplikace, uživatelská aplikační přiřazení a preference i notifikační typy, šablony, rozesílky a logy. Vytvoření a úplné smazání aplikace zůstává pouze globálnímu applications.manage nebo superadminovi.

GET `/applications/:appCode/i18n/:locale` — překlady notifikačních typů

Vrátí plochou mapu překladů (Record<string, string>) pro daný appCode a locale. FE může mapu přímo nahrát do i18n knihovny (vue-i18n, i18next, …) bez další transformace.

http

GET /api/applications/crm/i18n/cs
Authorization: Bearer <token>

Response

json

{
  "code": "OK",
  "response": {
    "notifications.types.new_task.title": "Nový úkol",
    "notifications.types.new_task.description": "Oznámení o přiřazení nového úkolu",
    "notifications.types.deal_closed.title": "Obchod uzavřen",
    "notifications.types.deal_closed.description": "Notifikace při uzavření obchodu",
    "notifications.types.generic.title": "Obecná notifikace",
    "notifications.types.generic.description": "Testovací / obecné oznámení"
  }
}

Klíč	Zdroj
`notifications.types.<code>.title`	`notification_types.name`
`notifications.types.<code>.description`	`notification_types.description` (vynechá se, pokud `null`)

TIP

Endpoint nevyžaduje SuperAdmin — slouží FE pro vykreslení názvu typu v Nastavení / Inboxu. Locale je zatím průchozí parametr; samotná tabulka notification_types ukládá texty bez locale, ale endpoint je již nachystaný na budoucí překladovou tabulku.

Workflow: nastavení nové aplikace

Kompletní postup pro nastavení nové aplikace:

1. Vytvořte aplikaci

bash

POST /api/applications
{ "code": "moje-app", "name": "Moje Aplikace" }

2. Vytvořte oprávnění

bash

POST /api/applications/moje-app/permissions
{ "code": "documents.read", "type": "binary", "groupName": "Dokumenty" }

POST /api/applications/moje-app/permissions
{ "code": "documents.edit", "type": "tiered", "groupName": "Dokumenty" }

3. Vytvořte role

bash

POST /api/applications/moje-app/roles
{ "code": "viewer", "description": "Pouze čtení" }

POST /api/applications/moje-app/roles
{ "code": "editor", "description": "Čtení a editace" }

4. Přiřaďte oprávnění rolím

bash

# Role "viewer" — jen čtení
PUT /api/applications/moje-app/roles/1/permissions
{ "permissions": [{ "permissionId": 1, "accessLevel": "allowed" }] }

# Role "editor" — čtení + editace
PUT /api/applications/moje-app/roles/2/permissions
{
  "permissions": [
    { "permissionId": 1, "accessLevel": "allowed" },
    { "permissionId": 2, "accessLevel": "edit" }
  ]
}

5. Přidejte app admina (volitelně)

bash

POST /api/users/admins/apps/moje-app
{ "email": "admin@firma.cz" }

6. Přiřaďte uživatelům role

bash

PUT /api/users/jan.novak@firma.cz/apps/moje-app/roles
{ "roleIds": [2] }

7. Testujte oprávnění

bash

POST /api/check
{
  "email": "jan.novak@firma.cz",
  "app": "moje-app",
  "permission": "documents.edit"
}

Aplikace (/applications) ​

GET /applications — seznam aplikací ​

Response ​

GET /applications/:appCode — detail aplikace ​

Response ​

POST /applications — vytvoření aplikace ​

Request body ​

Response 201 Created ​

PUT /applications/:appCode — aktualizace aplikace ​

Request body ​

DELETE /applications/:appCode — smazání aplikace ​

Response 204 No Content ​

Katalog entit aplikace ​

Seznam konkrétních entit ​

Omezení správy panelu na jednu aplikaci ​

GET /applications/:appCode/i18n/:locale — překlady notifikačních typů ​

Response ​

Workflow: nastavení nové aplikace ​

1. Vytvořte aplikaci ​

2. Vytvořte oprávnění ​

3. Vytvořte role ​

4. Přiřaďte oprávnění rolím ​

5. Přidejte app admina (volitelně) ​

6. Přiřaďte uživatelům role ​

7. Testujte oprávnění ​

Aplikace (`/applications`)

GET `/applications` — seznam aplikací

Response

GET `/applications/:appCode` — detail aplikace

Response

POST `/applications` — vytvoření aplikace

Request body

Response `201 Created`

PUT `/applications/:appCode` — aktualizace aplikace

Request body

DELETE `/applications/:appCode` — smazání aplikace

Response `204 No Content`

Katalog entit aplikace

Seznam konkrétních entit

Omezení správy panelu na jednu aplikaci

GET `/applications/:appCode/i18n/:locale` — překlady notifikačních typů

Response

Workflow: nastavení nové aplikace

1. Vytvořte aplikaci

2. Vytvořte oprávnění

3. Vytvořte role

4. Přiřaďte oprávnění rolím

5. Přidejte app admina (volitelně)

6. Přiřaďte uživatelům role

7. Testujte oprávnění