Správa uživatelů přes API

Co je potřeba odlišit

Při práci s uživateli přes API rozlišujte dvě samostatné operace:

Založení globálního uživatele – uživatel vznikne na úrovni služby.
Přidání uživatele do konkrétní firmy – uživatel získá přístup do vybrané firmy a konkrétní roli.

Bez přidání do firmy nebude mít samotné založení uživatele praktický dopad na přístup do firmy.

💡 Info: Postupy níže jsou ověřené v aplikaci Postman vůči cloudové instanci Flexi.

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

Globálního uživatele založíte požadavkem PUT nebo POST na endpoint /u.json

Podporuje JSON v těle požadavku. Dostupné položky k editaci lze zjistit dotazem GET na uvedený endpoint /u.json

Práva serveru (vhodné pro roli ADMIN) s hodnotami true/false odpovídající tomuto nastavení:

createCompany > povolí zakládat firmy
deleteCompany > povolí mazání firem
createUser > povolí zakládat uživatelé
changePassword > povolí měnit uživatelům heslo
grantPermisson > povolí udělovat oprávnění uživatelům
licenseMgmt > povolí spravovat licence

Postup

Pošlete PUT na endpoint /u
Nastavte hlavičku Content-Type: application/json.
V JSON těle uveďte údaje, které chcete upravit
Po úspěšném provedení vznikne globální uživatel.

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/u.json
Content-Type: application/json
{
    "username": "json",
    "givenName": "name",
    "familyName": "familyN",
    "email": "json@admin.cz",
    "userType": "READ_ONLY",
    "password": "heslo_uzivaele_123",
    "blocked": false,
    "permissions": {
        "manageAll": false,
        "createCompany": false,
        "deleteCompany": false,
        "createUser": false,
        "changePassword": false,
        "grantPermission": false,
        "licenseMgmt": false
    },
    "defaultRole": "UZIVATEL",
    "overrideRole": false,
    "apiAccessEnabled": false
}

Tímto voláním založíte uživatele json.

Editace uživatele

Editace uživatele probíhá voláním PUT na endpoint /u/{uzivatel}.json

a podporuje JSON zápis v těle požadavku.

Postup

Pošlete PUT na endpoint /u/{uzivatel}.json
Nastavte hlavičku Content-Type: application/json.
V JSON těle uveďte údaje, které chcete upravit

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/u/api_new.json
Content-Type: application/json
{
    "email": "new_email@email.cz"
}

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 provedete přes firemní endpoint evidence uživatelů.

Postup

Pošlete PUT na endpoint /c/{firma}/uzivatel
Nastavte hlavičku Content-Type: application/json
V JSON těle uveďte uživatele a roli, kterou má mít v dané firmě

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel
Content-Type: application/json
{ "winstrom": { "uzivatel": [ { "id": "code:api_new", "role": "code:ADMIN" } ] } }

V uvedeném příkladu se uživatel api_new přidá do firmy sk_firma_cloud s rolí ADMIN.

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

Editace role uživatele na firmě

Stejně jako přidání, editace uživatele probíhá voláním PUT na endpoint /c/{firma}/uzivatel

s hodnotami v těle požadavku v JSON.

Postup

Pošlete PUT na endpoint /c/{firma}/uzivatel
Nastavte hlavičku Content-Type: application/json.
V JSON těle uveďte údaje, které chcete upravit, třeba změníme roli na SKLADNIK

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/c/flexi_gui_s_r_o_/uzivatel
Content-Type: application/json
{
  "winstrom": {
    "uzivatel": [
      {
        "id": "code:api_new",
        "role": "code:SKLADNIK"
      }
    ]
  }
}

Odebrání uživatele z firmy

Pokud potřebujete uživateli zrušit přístup do konkrétní firmy, smažte jeho vazbu na firmu v evidenci uzivatel.

Postup

Pošlete PUT na endpoint /c/{firma}/uzivatel.
Nastavte hlavičku Content-Type: application/json.
V těle použijte akci delete a identifikaci uživatele.

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel
Content-Type: application/json
{ "winstrom": { "uzivatel": [ { "@action": "delete", "id": "code:api_new" } ] } }

Tímto voláním odeberete uživatele api_new z firmy sk_firma_cloud.

⚠️ Warning: Tímto krokem uživatele odeberete z konkrétní firmy, ale pokud to je jeho jediná přidělená firma, vymaže se globálně.

Pokud jsou na uživatele již historicky navázané záznamy v databázi, odebrání uživatelé neprojde, v takovém případně se provádí Blokace uživatele.

Blokace uživatele

Blokace uživatele normal_v1 v cURL:

curl -u "user:password" -X POST -d "blocked=true" "https://moje.flexibee.eu/u/normal_v1.json"

V Postman:

POST

https://alpe.flexibee.eu:5434/u/normal_v1.json

Body JSON

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

⚠️ Warning: Blokací uživatele uvolníte jeho licenci a znemožníte jeho přihlášení. Odblokování provedete stejně s hodnotou "false".

Výpis všech uživatelů

Pro kontrolu všech globálních uživatelů použijte výpis nad endpointem /u.json.

Postup

GET

https://alpe.flexibee.eu:5434/u.json

Vrací seznam všech uživatelů.

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

Pokud potřebujete zjistit, kteří uživatelé jsou připojení do konkrétní firmy, použijte firemní evidenci uživatelů.

Postup

GET

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/uzivatel.json?limit=0&detail=full

Vrací uživatele navázané ke konkrétní firmě.

⚠️ Warning
Parametr limit=0 ruší výchozí limit 20 záznamů na neomezeno, pro získání všech uživatelů dané firmy.

Parametr detail=full zobrazuje všechny pole a jejích hodnoty pro úplný detail.

Výpis rolí ve firmě

Dostupné role ve firmě zjistíte přes dotaz nad evidencí role.

Postup

Pošlete GET na c/{firma}/role.json
V JSON těle nastavte požadovaný detail výstupu.
Pro přehledný seznam vraťte jen ID, kód a název.

Ověřený příklad

GET

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/role.json?limit=0

Takto získáte přehled rolí dostupných ve vybrané firmě.

⚠️ Warning
Parametr detail=full zde vrací seznam všech nastavených práv, tj. přes 10 000 řádků za každou 1 roli. Pokud je nutno číst nastavení práv na roli, doporučením je omezit dotaz pouze za jednu, například za roli ADMIN:

https://alpe.flexibee.eu:5434/c/sk_firma_cloud/role/code:ADMIN.json?detail=full

Přehled endpointů

Operace	Metoda a endpoint	Poznámka
Vytvoření globálního uživatele	PUT nebo POST `/u`	JSON tělo
Editace globálního uživatele	PUT `/u`	JSON tělo
Editace uživatele na firmě	PUT `/c/{firma}/uzivatel`	JSON tělo
Přidání uživatele do firmy	PUT `/c/{firma}/uzivatel`	JSON tělo
Odebrání uživatele z firmy	PUT `/c/{firma}/uzivatel`	`@action: delete`
Blokace uživatele	POST`/u/{uzivatel}.json`	hodnota blocked=true se v Postman posílá přes body typu x-www-form-urlencoded
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`	Doporučený custom detail opatrně s ?detail=full!

Na co dát pozor

⚠️ Warning: Založení uživatele a přidání do firmy jsou dvě oddělené operace. Je potřeba provést obě.

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

⚠️ Warning: Práci s uživateli přes API je vhodné vyladit na testovacím prostředí či vůči testovací databázi.

⚠️ Warning: Role jsou prozatím pouze pro čtení, nelze do nich v API zapisovat.

Související články

Dávkové operace, Batch API
- https://podpora.flexibee.eu/cs/articles/4786921-davkove-operace
Uživatelské role v API
- https://podpora.flexibee.eu/cs/articles/13396639-uzivatelske-role-rest-api

Související články