API pracuje s uživatelskými daty, proto jej nelze používat bez autentizace.
API mPOHODA podporuje dva způsoby autentizace, a to prostřednictvím:
API klíče
Api klíč je unikátní identifikátor sloužící k identifikaci uživatele a firmy. Jedná se o tajnou informaci a je tedy nutné ho uchovat na bezpečném místě, podobně jako např. hesla.
přístupového tokenu (access tokenu)
Přístupový token rovněž slouží k identifikaci uživatele a firmy, jeho platnost je však časově omezená. Klient obdrží přístupový token po úspěšné autentizaci na autentizačním serveru, s využitím OAuth2 a Client Credentials Grant Type. Token je poté zaslán klientem spolu s požadavkem na API.
upozornění Z hlediska větší bezpečnosti doporučujeme použít přístup pomocí přístupového tokenu.
Autentizace se pro jednotlivé uživatele firmy v aplikaci mPOHODA spravuje v agendě API. Právo na vytvoření nového přístupového kódu má pouze administrátor firmy.
Vygenerovaný autentizační kód je svázán s firmou, ve které byl vygenerován, a uživatelem, který jej vytvořil. V požadavcích tedy není potřeba identifikaci uživatele či firmy žádným dalším způsobem specifikovat.
info Odchodem uživatele z firmy dojde k zneplatnění přístupových údajů a nelze je nadále používat. V případě odebrání administrátorských práv uživateli se uplatňují na API přístupová práva dle nastavení daného uživatele.
1. API klíč
Api klíč je nutné vložit do hlavičky každého požadavku. Tím se zároveň definuje, pro jakého uživatele a firmu se požadavek provádí.
| Název | Typ | Popis |
|---|---|---|
Api-Key |
string | API klíč vygenerovaný v agendě API |
Api-Key: 4bef30e89dcd352e8371da053b16f0cf6faf27c31f780f52c3a3cb7604a81a85Postup pro získání API klíče je popsán v následujícím textu.
Vygenerování API klíče
Nový API klíč vygenerujete v agendě API kliknutím na tlačítko Nový klíč v sekci Přístup pomocí API klíče, zadáním názvu klíče a potvrzením kliknutím na tlačítko Vytvořit.
Klíč se zobrazí v dialogovém okně. Jedná se o tajnou informaci, kterou je nutné uložit na bezpečném místě mimo aplikaci mPOHODA.
upozornění Po zavření dialogu nelze z bezpečnostních důvodů klíč znovu zobrazit.
2. Token
Token je nutné vložit do hlavičky každého požadavku. Tím se zároveň definuje, pro jakého uživatele a firmu se požadavek provádí.
| Název | Typ | Popis |
|---|---|---|
Authorization |
string | Token ve tvaru Bearer {token} |
Authorization: Bearer eyJhbGciOi...Získání tokenu probíhá dle standardu OAuth2 s využitím Client Credentials Grant Type. Jiné Grant Type nejsou v současné době podporovány.
upozornění Tento typ je vhodný pouze pro aplikace, které umožňují bezpečné uložení autentizačních údajů Client Id a Client Secret, zejména serverové. Zároveň je vhodný pouze pro aplikace, kde uživatel (i firma) může být pevně specifikován (údaji Client Id a Client Secret) a není tak vyžadováno přihlášení různých uživatelů. Jedná se např. o různá automatizovaná zpracování dat, třeba z nějakého e-shopu.
Postup je popsán v následujícím textu.
Vygenerování klienta
Pro získání tokenu je třeba nejprve vygenerovat klienta, který je určen údaji ClientId a Client Secret.
Nového klienta vytvoříte v agendě API kliknutím na tlačítko Nový klient v sekci Přístup pomocí přístupového tokenu, zadáním názvu klienta a potvrzením kliknutím na tlačítko Vytvořit.
Pro přístup pomocí tokenu se vytvoří Client Id a Client Secret, které se zobrazí v dialogovém okně. Jedná se o tajné údaje (zejména Client Secret), které je nutné uložit na bezpečném místě mimo aplikaci mPOHODA.
upozornění Po zavření dialogu nelze z bezpečnostních důvodů Client Secret znovu zobrazit.
Získání tokenu
Token získáte posláním požadavku na token endpoint na autentizačním serveru, který běží na adrese https://ucet.pohoda.cz. Adresa endpointu je https://ucet.pohoda.cz/connect/token, lze ji zjistit i z konfigurace dostupné na https://ucet.pohoda.cz/.well-known/openid-configuration.
POST https://ucet.pohoda.cz/connect/token| Název | Typ | Popis |
|---|---|---|
Content-Type |
string | Hodnota application/x-www-form-urlencoded |
| Název | Typ | Popis |
|---|---|---|
grant_type |
string | řetězec client_credentials |
client_id |
string | hodnota Client Id z administrace v agendě API |
client_secret |
string | hodnota Client Secret z administrace v agendě API |
scope |
string | řetězec Mph.OpenApi.Access.Cz |
grant_type=client_credentials&client_id=...&client_secret=...&scope=Mph.OpenApi.Access.Cz| Pole | Typ | Popis | |
|---|---|---|---|
access_token |
string |
vygenerovaný přístupový token | |
expires_in |
int |
platnost tokenu (v sekundách) | |
token_type |
string |
typ tokenu | |
scope |
string |
specifikuje API scope (resource), pro který se přístupový token získá. |
{
"access_token": "eyJhbGciOi...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "Mph.OpenApi.Access.Cz"
}
Platnost tokenu
Získaný token má časově omezenou platnost, dle hodnoty pole expires_in v odpovědi. Po vypršení platnosti nelze token žádným způsobem obnovit a je potřeba stejným způsobem získat nový token. Tzv. refresh token se v případě použitého Grant Type Client Credentials nepoužívá.