API PSB od eConnect používá OAuth 2.0 pro autentifikaci. Každý API požadavek obsahuje Bearer token, který získáte z Identity Server eConnect. Tento token je platný jednu hodinu a obsahuje veškeré informace, které PSB potřebuje k určení toho, kdo jste, jménem jaké organizace pracujete a co máte povoleno dělat.

V tomto článku projdete celým procesem autentifikace: od pochopení autentifikačního modelu po žádost o tokeny a jejich používání.

PSB pracuje se čtyřmi vrstvami identifikace. Každá vrstva odpovídá na jinou otázku a společně určují přístup k API.

Vrstva 1: Aplikace (clientId + clientSecret) Identifikuje software, který se připojuje k PSB. Softwarový partner zpravidla používá jedinou sadu clientId/clientSecret pro všechny své koncové zákazníky. To zjednodušuje onboarding: koncoví zákazníci musí vyplnit méně technických údajů a pravděpodobnost konfiguračních chyb je menší. Všechna clientId mají stejný scope (ap), a tedy stejná funkční oprávnění.

Vrstva 2: Koncový zákazník (username + password) Identifikuje, jménem jaké organizace se pracuje. Pro každého koncového zákazníka eConnect vytvoří PSB uživatelský účet propojený s jedním nebo více partyId (číslo obchodní komory, DIČ, OIN, belgické číslo podniku). V toku Resource Owner Password Credentials zadáte username a password, které určují, ke kterým party máte přístup. V toku Client Credentials to není nutné, protože oprávnění jsou přímo propojena s aplikací. Uživatelské jméno a heslo se obvykle poskytují přímo koncovému zákazníkovi; koncový zákazník je pak sám sdílí s dodavatelem softwaru. Při vytváření uživatelského účtu koncového zákazníka v rámci vlastního PSB tenantu (například pro integraci 4PS Business Central) nesmí heslo obsahovat speciální znaky, s výjimkou vykřičníku (!).

Vrstva 3: Prostředí (tenantId) Poskytuje administrativní oddělení mezi prostředími. Každý koncový zákazník zpravidla dostane vlastní tenant, což zaručuje úplné oddělení zpráv, konfigurace a logování. Někteří softwaroví partneři umisťují více koncových zákazníků do jednoho tenantu pro centrální správu; jiní volí samostatný tenant pro každého zákazníka pro maximální izolaci. Tenanty nelze sloučit, ale uživatelské účty lze upravit nebo rozšířit.

Vrstva 4: Logování (subscription key, legacy) Header Subscription-Key byl původně určen pro identifikaci v log souborech API. Pro API PSB tento header již není povinný. Pokud jej odešlete, hodnota musí být platná. eConnect někdy stále vydává subscription key, protože umožňují sledování každého požadavku v logách ke konkrétnímu softwarovému partnerovi. Poznámka: pro platformu eConnect (platform.econnect.eu) je subscription key stále povinný.

Token se žádá odesláním POST požadavku na endpoint /connect/token Identity Serveru.

Toto je doporučený tok pro integrace server-server. Odešlete pouze svůj clientId a clientSecret.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=vas-client-id
&client_secret=vas-client-secret
&scope=ap

V tomto toku zadáte také uživatelské jméno a heslo. Je to užitečné, když jsou oprávnění vázána na konkrétního koncového uživatele.

POST /connect/token HTTP/1.1
Host: identity.econnect.eu
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=vas-client-id
&client_secret=vas-client-secret
&username=vase-uzivatelske-jmeno
&password=vase-heslo
&scope=ap

Při úspěšném požadavku obdržíte JSON objekt obsahující access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "ap"
}

Pole expires_in udává, kolik sekund je token platný. Výchozí hodnota je 3600 sekund (1 hodina).

Token Bearer zahrňte do headeru Authorization u každého API požadavku na PSB:

GET /api/v1/me HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

PSB validuje token u každého požadavku. Pokud je token neplatný nebo vypršel, obdržíte odpověď 401 Unauthorized.

Bearer token je platný 3600 sekund. Po vypršení musíte požádat o nový token přes stejný endpoint /connect/token. Neexistuje samostatný refresh tok: jednoduše zopakujete žádost o token.

V praxi je nejlepší požádat o nový token krátce před vypršením aktuálního, například po 3500 sekundách. Tím se zabrání selhání API volání kvůli vypršenému tokenu, zatímco je požadavek na cestě.

1. Token vyžádán                → platný do t+3600s
2. Po ~3500s: nový token        → starý token ještě ~100s platný
3. Přepnutí na nový token

Token uložte ve Vaší aplikaci a používejte jej pro více požadavků. Nežádejte nový token u každého API volání, protože to zbytečně zatěžuje Identity Server.

Standardně softwarový partner používá jednu sadu clientId/clientSecret pro všechny koncové zákazníky. V některých situacích je vhodné používat více sad:

• Oddělení testu a produkce. Použijte samostatný clientId pro akceptační prostředí (accp-identity.econnect.eu) a pro produkci (identity.econnect.eu). Tím se zabrání náhodnému použití testovacích údajů v produkci.
• On-premise instalace. Pokud software běží u koncového zákazníka a zákazník má přístup ke konfiguraci, sdílený clientSecret může představovat bezpečnostní riziko. Se samostatným clientId na zákazníka omezíte škodu v případě úniku přihlašovacích údajů.
• Oddělená oprávnění na integraci. Pokud budujete více samostatných aplikací, z nichž každá potřebuje jinou API funkcionalitu (například fakturační modul a modul objednávek), můžete pro každou aplikaci použít vlastní clientId pouze s potřebnými oprávněními.

Zrušení clientSecret se týká pouze příslušného clientId. Ostatní zákazníci nebo integrace nejsou dotčeni.

Pokud obdržíte 401 při API volání na PSB, nejprve zkontrolujte, zda je token ještě platný. Ve většině případů vypršel a stačí vyžádat nový token.

Následující diagram ukazuje, jak aplikace vyžádá token z Identity Serveru a poté tento token použije pro volání API PSB.

Kompletní API reference včetně všech endpointů a formátů požadavků/odpovědí je k dispozici v interaktivní Swagger dokumentaci.