Přeskočit na hlavní obsah

Správa uživatelů přes API

Následující postupy shrnují ověřené volání pro správu uživatelů v cloudovém prostředí ABRA Flexi přes API.

Autor: Petr Pech

Při práci s uživateli přes API rozlišujte dvě samostatné operace: založení globálního uživatele, který vznikne na úrovni služby, a přidání uživatele do konkrétní firmy, kde získá přístup a roli. Bez přidání do firmy nemá samotné založení uživatele na přístup do firmy praktický dopad.

ℹ️ Globální uživatelé žijí mimo databázi firmy, na endpointu /u. Uživatelé přiřazení k firmě jsou naopak evidence /c/{firma}/uzivatel uvnitř dané firmy.

Vytvoření globálního uživatele

Globálního uživatele založíte požadavkem PUT nebo POST na endpoint /u.json s hlavičkou Content-Type: application/json a s údaji v těle požadavku. Dostupné položky zjistíte dotazem GET na tentýž endpoint.

PUT https://demo.flexibee.eu/u.json
Content-Type: application/json

{
  "username": "novy_uzivatel",
  "givenName": "Jan",
  "familyName": "Novák",
  "email": "jan.novak@example.com",
  "userType": "READ_ONLY",
  "password": "tajne_heslo_123",
  "blocked": false,
  "permissions": {
    "manageAll": false,
    "createCompany": false,
    "deleteCompany": false,
    "createUser": false,
    "changePassword": false,
    "grantPermission": false,
    "licenseMgmt": false
  },
  "defaultRole": "UZIVATEL",
  "overrideRole": false,
  "apiAccessEnabled": false
}

Typ uživatele

Hodnota userType je kontrolovaná — neplatná hodnota vrací 400 s kódem invalidUserTypeUsed a uživatel nevznikne. Používané hodnoty jsou NORMAL, READ_ONLY, REST_API a AUTOMATIC.

Práva serveru

Objekt permissions odpovídá právům serveru, jak je vidíte v aplikaci. Vhodné jsou zejména pro roli ADMIN a nabývají hodnot true a false:

Právo

Co povoluje

manageAll

Správu všech firem na instanci.

createCompany

Zakládání firem.

deleteCompany

Mazání firem.

createUser

Zakládání uživatelů.

changePassword

Změnu hesla uživatelům.

grantPermission

Udělování oprávnění uživatelům.

licenseMgmt

Správu licencí.

Editace globálního uživatele

Editace probíhá požadavkem PUT na endpoint /u/{uzivatel}.json; v těle uveďte jen ty položky, které chcete změnit.

PUT https://demo.flexibee.eu/u/novy_uzivatel.json
Content-Type: application/json

{
  "email": "novy.email@example.com"
}

Dotaz na neexistujícího uživatele vrací 404 s kódem uzivatelNeexistuje.

Přidání uživatele do firmy

Po založení globálního uživatele je potřeba přidat ho do konkrétní firmy. To se provádí požadavkem PUT na firemní evidenci /c/{firma}/uzivatel, kde uvedete uživatele a roli, kterou má v dané firmě mít:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{ "winstrom": { "uzivatel": [ { "id": "code:novy_uzivatel", "role": "code:ADMIN" } ] } }

V uvedeném příkladu se uživatel novy_uzivatel přidá do firmy demo s rolí ADMIN. Neexistující role skončí chybou notObjectIdentifier a záznam se nezaloží.

🚨 Firemní evidence si nekontroluje, že globální uživatel skutečně existuje — při překlepu v id se záznam bez chyby založí a vrátí created: 1. Vznikne tak uživatel firmy, ke kterému žádný globální účet nepatří. Po přidání proto vždy porovnejte výpis /c/{firma}/uzivatel s výpisem /u.json.

ℹ️ Výchozí role při založení globálního uživatele (defaultRole) a role přidělená ve firmě jsou dvě různé věci.

Editace role uživatele na firmě

Role se mění stejným požadavkem jako přidání — PUT na /c/{firma}/uzivatel s novou hodnotou role:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{
  "winstrom": {
    "uzivatel": [
      {
        "id": "code:novy_uzivatel",
        "role": "code:SKLADNIK"
      }
    ]
  }
}

Odebrání uživatele z firmy

Potřebujete-li uživateli zrušit přístup do konkrétní firmy, smažte jeho vazbu na firmu akcí delete v evidenci uzivatel:

PUT https://demo.flexibee.eu/c/demo/uzivatel
Content-Type: application/json

{ "winstrom": { "uzivatel": [ { "@action": "delete", "id": "code:novy_uzivatel" } ] } }

⚠️ Tímto krokem uživatele odeberete z konkrétní firmy — pokud to ale byla jeho jediná přidělená firma, smaže se globálně. Jsou-li na uživatele historicky navázané záznamy v databázi, odebrání neprojde; v takovém případě použijte blokaci uživatele.

Blokace uživatele

Blokace se provádí požadavkem POST na /u/{uzivatel}.json s příznakem blocked. Volitelný blocked@message uloží důvod:

POST https://demo.flexibee.eu/u/novy_uzivatel.json
Content-Type: application/json

{
  "blocked": true,
  "blocked@message": "Blocked from API"
}

Hodnotu blocked lze poslat i jako data formuláře (blocked=true).

⚠️ Blokací uživatele uvolníte jeho licenci a znemožníte mu přihlášení. Odblokování provedete stejným požadavkem s hodnotou false.

Výpis všech uživatelů

Přehled všech globálních uživatelů vrátí GET na /u.json:

GET https://demo.flexibee.eu/u.json

U každého uživatele jsou vždy vyplněné username, userType, blocked, permissions, overrideRole, createDt, licenseGroup, twoPhaseAuthEnabled, resetTokenFilled a apiAccessEnabled. Položky email, givenName, familyName, defaultRole, lastLoginDate a lastApiDate se v odpovědi objeví jen tehdy, když mají hodnotu.

📝 Ve výpisu je users.user polem, kdežto dotaz na jednoho uživatele (/u/{uzivatel}.json) vrací users.user jako jediný objekt. Kód, který odpověď zpracovává, na to musí být připravený.

Výpis uživatelů z konkrétní firmy

Uživatele navázané ke konkrétní firmě vrátí firemní evidence:

GET https://demo.flexibee.eu/c/demo/uzivatel.json?limit=0&detail=full

⚠️ Parametr limit=0 ruší výchozí limit 20 záznamů, takže dostanete všechny uživatele dané firmy. Parametr detail=full vypíše všechna pole a jejich hodnoty — viz úrovně detailu.

Výpis rolí ve firmě

Dostupné role ve firmě zjistíte dotazem nad evidencí role. Pro přehledný seznam si vyžádejte jen ID, kód a název:

GET https://demo.flexibee.eu/c/demo/role.json?limit=0&detail=custom:id,kod,nazev

🚨 detail=full zde vrací seznam všech nastavených práv, tedy přes 10 000 řádků na jednu roli. Potřebujete-li práva přečíst, omezte dotaz na jedinou roli: GET /c/{firma}/role/code:ADMIN.json?detail=full.

Role jsou přes API pouze ke čtení — pokus o jejich import vrací 400 s kódem importNotAllowed.

Přehled endpointů

Operace

Metoda a endpoint

Poznámka

Vytvoření globálního uživatele

PUT nebo POST /u.json

JSON tělo

Editace globálního uživatele

PUT /u/{uzivatel}.json

JSON tělo, jen měněné položky

Přidání uživatele do firmy

PUT /c/{firma}/uzivatel

JSON tělo s id a role

Editace role uživatele na firmě

PUT /c/{firma}/uzivatel

JSON tělo

Odebrání uživatele z firmy

PUT /c/{firma}/uzivatel

akce @action: delete

Blokace uživatele

POST /u/{uzivatel}.json

příznak blocked; lze poslat i jako data formuláře

Výpis všech uživatelů

GET /u.json

globální uživatelé

Výpis uživatelů z firmy

GET /c/{firma}/uzivatel.json?limit=0&detail=full

uživatelé konkrétní firmy

Výpis rolí

GET /c/{firma}/role.json?limit=0

volte vlastní detail, opatrně s detail=full

Na co dát pozor

  • Založení uživatele a přidání do firmy jsou dvě oddělené operace — je potřeba provést obě.

  • Firemní evidence uživatelů neověřuje existenci globálního účtu, takže překlep v uživatelském jménu se neprojeví chybou.

  • Výpisy s detail=full mohou být výrazně rozsáhlé a méně přehledné.

  • Role jsou přes API pouze ke čtení, zapisovat do nich nelze.

  • Práci s uživateli přes API si vylaďte na testovacím prostředí nebo vůči testovací databázi.

Související

Související články
Dostali jste odpověď na svou otázku?