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 na endpoint /u Údaje se neposílají v JSON těle, ale jako parametry v URL.

Do budoucna se vytváření uživatelů změní. Plánovaná je podpora zasílání parametrů v JSON těle požadavku, místo stávajícího odesílání přes hlavičku.

Používané parametry a jejích význam

jmeno > unikátní uživatelské jméno
heslo > heslo pro přihlášení
email > unikátní email uživatele
default_role > výchozí role uživatele
userType > Typ uživatele: NORMAL, REST_API, READ_ONLY, vysvětlení jednotlivých typů
blocked > pro blokování/zablokování uživatele
manage_all > hodnotou true uživatele přidáte do všech firem, odpadá tak nutnost jej přidávat v následném kroku zvlášť

Parametry udělující práva serveru (vhodné pro roli ADMIN) s hodnotami true/false odpovídající tomuto nastavení:

create_company > povolí zakládat firmy
delete_company > povolí mazání firem
create_user > povolí zakládat uživatelé
change_password > povolí měnit uživatelům heslo
grant_permisson > povolí udělovat oprávnění uživatelům
license_mgmt > povolí spravovat licence

Postup

Pošlete PUT na endpoint /u
Do URL doplňte přihlašovací jméno, heslo, e-mail a výchozí roli.
Po úspěšném provedení vznikne globální uživatel.

Ověřený příklad

PUT

https://alpe.flexibee.eu:5434/u?jmeno=api_new&heslo=Heslo123&email=api_new@api.cz&default_role=SKLADNIK

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

⚠️ Warning: Endpoint podle ověření nebere JSON tělo požadavku. Pokud data pošlete v body, vytvoření uživatele nemusí proběhnout. Podpora bude doplněná v příštích verzích.

Editace uživatele

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

a podporuje již 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 `/u`	Parametry pouze v URL
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