Spôsoby autentizácie

API pracuje s uživateľskými údajmi, preto ho nie je možné používať bez autentizácie.

API mPOHODA podporuje dva spôsoby autentizácie, a to prostredníctvom:

• API kľúča

  Api kľúč je unikátny identifikátor slúžiaci k identifikácii užívateľa a firmy. Jedná sa o tajnú informáciu a je potrebné ho uchovať na bezpečnom miestť, podobne ako napr. hesla.

• prístupového tokena (access tokena)

  Prístupový token rovnako slúží k identifikácii užívateľa a firmy, jeho platnosť je však časovo obmedzená. Klient obdrží prístupový token po úspešnej autentizácii na autentizačnom serveri, s využitím OAuth2 a Client Credentials Grant Type. Token je potom posielaný klientom spolu s požadavkou na API.

  upozornění Z hľadiska väčšej bezpečnosti odporúčame používať prístup pomocou prístupového tokena.

Autentizácia sa pre jednotlivých užívateľom firmy v aplikácii mPOHODA spravuje v agende API. Právo na vytvorenie nového prístupového kódu má iba administrátor firmy.

Vygenerovaný autentizačný kód je zviazaný s firmou, v ktorej bol vygenerovaný a užívateľom, ktorý ho vytvoril. V požiadavkách preto nie potrebné identifikáciu užívateľa, alebo firmy žiadným ďalším spôsobom špecifikovať.

info Odchodom užívateľa z firmy dôjde k zneplatneniu prístupových údajov a nie je ich možné ďalej používať. V prípade odobratia administrátorských práv užívateľovi, sa uplatňují na API prístupové práva, podľe nastavenia daného uživateľa.

1. API kľúč

Api kľúč je potrebné vložiť do hlavičky každej požiadavky. Tým sa zároveň definuje, pre akého užívateľa a firmu sa požiadavka vykonáva.

Api-Key: 4bef30e89dcd352e8371da053b16f0cf6faf27c31f780f52c3a3cb7604a81a85

Postup pre získanie API kľúča, je popísaný v následujúcom texte.

Vygenerovanie API kľúča

Nový API kľúč vygenerujete v agende API kliknutím na tlačidlo Nový kľúč v sekcii Prístup pomocou API kľúča, zadaním názvu kľúča a potvrdením kliknutím na tlačidlo Vytvoriť.

Kľúč sa zobrazí v dialógovom okne. Jedná sa o tajnú informáciou, ktorú je potrebné uložiť na bezpečnom mieste, mimo aplikáciu mPOHODA.

upozornění Po zatvorení dialógu nie je možné z bezpečnostných dôvodov kľúč znova zobraziť.

2. Token

Token je potrebné vložiť do hlavičky každej požiadavky. Tým sa zároveň definuje, pre akého užívateľa a firmu sa požiadavka vykonáva.

Authorization: Bearer eyJhbGciOi...

Získanie tokenu prebieha podľa štandardu OAuth2 s využitím Client Credentials Grant Type. Iné Grant Type nie sú v súčasnej dobe podporované.

upozornění Tento typ je vhodný iba pre aplikácie, ktoré umožňujú bezpečné uloženie autentizačných údajov Client Id a Client Secret, najmä serverové. Zároveň je vhodný iba pre aplikácie, kde užívateľ (a firma) môže byť pevne specifikovaný (údaje Client Id a Client Secret) a nie je tak vyžadované prihlásenie rôznych užívateľov. Jedna sa napr. o rôzne automatizované spracovanie údajov, napr. z e-shopu.

Postup je popísaný v následujúcom texte.

Vygenerovanie klienta

Pre získanie tokena je potrebné najskôr vygenerovať klienta, ktorý je určený údajmi ClientId a Client Secret.

Nového klienta vytvoríte v agende API kliknutím na tlačídlo Nový klient v sekcii Prístup pomocou prístupového tokenu, zadaním názvu klienta a potvrdením kliknutím na tlačidlo Vytvoriť.

Pre prístup pomocou tokena sa vytvorí Client Id a Client Secret, ktoré sa zobrazia v dialogovom okne. Jedná sa o tajné údaje (najmä Client Secret), ktoré je potrebné uložiť na bezpečnom mieste mimo aplikácie mPOHODA.

upozornění Po zatvorení dialógu nie je možné z bezpečnostných dôvodov Client Secret znovu zobraziť.

Získanie tokenu

Token získáte poslaním požadavky na token endpoint na autentizačnom serveri, ktorý beží na adrese https://ucet.pohoda.cz. Adresa endpointu je https://ucet.pohoda.cz/connect/token, je ju možné zistiť aj z konfigurácie dostupnej na https://ucet.pohoda.cz/.well-known/openid-configuration.

POST https://ucet.pohoda.cz/connect/token

grant_type=client_credentials&client_id=...&client_secret=...&scope=Mph.OpenApi.Access.Sk

Platnosť tokena

Získaný token má časovo obmedzenú platnosť, podľa hodnoty pole expires_in v odpovedi. Po vypršaní platnosti nie je možné token žiadným spôsobom obnoviť a je potrebné rovnakým spôsobom získať nový token. Tzv. refresh token sa v prípade použitého Grant Type Client Credentials nepoužíva.