Příručka registračí a autorizačí postup PSD2 pro třetí stray 1
Obsah Autetizace TPP... 3 Registračí a autetizačí resource vystaveé bakou... 4 1. Charakteristika iicializačí/registračí resource... 4 2. Charakteristika resource Iformace o registračích údajích aplikace... 9 3. Charakteristika resource Změa registračích údajů... 11 4. Charakteristika resource Smazáí aplikace... 14 5. Charakteristika resource Žádost o ový cliet_secret... 15 6. Charakteristika requestu a Autorizačí resource... 17 7. Charakteristika requestu Získáí/vystaveí tokeu... 20 8. Charakteristika requestu Zeplatěí tokeu... 22 2
Autetizace TPP Třetí straa, která chce využívat služby defiovaé v PSD2 musí mít liceci od árodího regulátora a příslušý certifikát vydaý pro služby PSD2. Předpokladem úspěšé autetizace je pak použití kvalifikovaého certifikátu typu QSEAL (elektroická pečeť) ebo QWAC (kvalifikovaý certifikát pro webové stráky) vydaého dle ormy ETSI od společosti I.CA pro idetifikaci komuikující třetí stray (také third party provider, dále TPP). Nutou podmíkou využití služeb PSD2 v KB je zasláí žádosti o připojeí do schráky api@kb.cz včetě veřejého certifikátu bez privátího klíče. Autetizačí certifikát třetí stray je vyžadová při avázaí zabezpečeého spojeí s bakou (ASPSP) komuikačím protokolem TLS. Autetizace je vyžadováa u všech resources, kromě autorizace klieta viz. kapitola Charakteristika requestu a Autorizačí resource, který zahajuje federovaý autetizačí proces KB. 3
Registračí a autetizačí resource vystaveý bakou Proces erollmetu klieta utý pro pochopeí registrace aplikace a práce s tokey je detailě popsá v dokumetaci českého ope bakig stadardu (kokrétě v kapitole Flow v procesu erollmetu klieta do aplikace TPP) Czech Ope Bakig Stadard. Nutou podmíkou pro využíváí služeb Iiciováí platby (PIS) a Iformace o účtu (AIS) je registrace aplikace třetí stray (viz ásledující kapitola). 1. Charakteristika iicializačí/registračí resource Zavoláím tohoto resource žádá TPP o dyamickou registraci svojí aplikace (v termiologii OAuth je to cliet_id). Pro zavoláí resource je potřeba použít platý certifikát. Výstupem jsou parametry cliet_id a cliet_secret, které TPP potřebuje pro astartováí a průchod autetizačím procesem uživatele (klieta baky). API klíč eí v Komerčí bace podporová. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /register POST https://api.kb.cz/serverapi/oauth2/v1/register request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Parametry hlavičky (header) requestu: Tpp_id strig y Registračí číslo určitého TPP. Parametry těla (body) requestu: applicatio_type web, ative y Typ aplikace, která bude používat cliet_id. V případě typu web je požadováo defiováí rediect_uris ve formátu webového uri v podobě http/s schéma. U typu ative je možé v redirect_uris zadat apř. applicatio package, resp. vlastí formát. Pozamka ative eí v Komerčí bace podporová redirect_uris Pole obsahující řetězce apř. ve formátu URL [Max 3x 2047 B] y Výčet URL kam je a koci přesměrováo flow autetizace. Autorizačí request musí obsahovat právě jedo z těchto zaregistrovaých URI v přesém formátu. cliet_ame strig [Max 255 B] y Jméo klietské aplikace cliet_ame#e-us strig [Max 1024 B] Jméo klietské aplikace v příslušém jazyce/kódováí. logo_uri URI [Max 2047 B] URI loga aplikace (resp. místo odkud je možé ho při registraci stáhout) cotact strig e-mail [Max 320 B] E-mail jako kotakt a zodpovědou osobu a straě klietské aplikace. 4
scopes Pole strigů [Max 10x 255 B] Pole aplikací požadovaých scopes. Při registraci jsou scopes validováy proti obsahu použitého certifikátu. Pole je case-sesitive a povoleé hodoty jsou "aisp" a "pisp". 5
Příklad requestu: POST https://api.kb.cz/serverapi/oauth2/v1/register HTTP/1.1 Accept-Ecodig: gzip,deflate x-request-id: 4512345 Cotet-Type: applicatio/jso; charset=utf-8 Host: api.kb.cz { } "applicatio_type": "web", "redirect_uris": ["https://www.mymultibak.cz/start", "https://www.mymultibak.cz/start2"], "cliet_ame": "Moje_uiverzali_baka", "cliet_ame#e-us": "My_cool_bak", "logo_uri": "https://www.mybak.cz/logo.pg", "cotact": "ifo@mybak.cz", "scopes": ["aisp","pisp"] Parametry hlavičky (header) respose: Cotet-Type Strig y Specificatio of required trasfer format. From the precoditio of techical specificatio of this API stadard, i this case, applicatio/jso format is primarily supported. x-request-id Strig Volitelý parametr pro idetifikaci (spárováí) TPP request / respose Parametry těla (body) respose: cliet_id Strig y Aplikaci přiřazeé cliet_id. Tímto ID je startová autetizačí proces a dekorováa komuikace při výměě code a refresh_tokeu. cliet_secret Strig y Cliet secret - password/toke vydaý IDP baky pro aplikaci (cliet_id) TPP api_key Strig y API klíč, který aplikace používá při komuikaci s API baky. Pokud baka API klíče epodporuje, vrátí hodotu NOT_PROVIDED applicatio_type web y Typ aplikace, která bude používat cliet_id. V případě typu web je požadováo defiováí rediect_uris ve formátu webového uri v podobě http/s schéma. redirect_uris Pole obsahující řetězce apř. ve y Výčet URL kam je a koci přesměrováo flow autetizace. Autorizačí request musí obsahovat právě 6
formátu URL [Max 3x 2047 B] jedo z těchto zaregistrovaých URI v přesém formátu. cliet_ame strig [Max 255 B] y Jméo klietské aplikace cliet_ame#e-us strig [Max 1024 B] Jméo klietské aplikace v příslušém jazyce/kódováí. logo_uri URI [Max 2047 B] URI loga aplikace (resp. místo odkud je možé ho při registraci stáhout) cotact strig e-mail [Max 320 B] E-mail jako kotakt a zodpovědou osobu a straě klietské aplikace. scopes Pole strigů [Max 10x 255 B] Pole aplikací požadovaých scopes. Při registraci jsou scopes validováy proti obsahu použitého certifikátu. Příklad respose bez chyby: HTTP/1.1 201 Created Cotet-Type: applicatio/jso; charset=utf-8 Accept-Ecodig: gzip,deflate x-request-id: 4512345 Host: api.kb.cz Cocetio: Keep-Alive Trasfer-Ecodig: chuked { } "cliet_id": "Moje_uiverzali_baka-1234", "cliet_secret": "AAjkk45sd78ad454gddd8712_4555g5g5g5gg", "cliet_secret_expires_at": 0, "api_key": "NOT_PROVIDED", "applicatio_type": "web", "redirect_uris": ["https://www.mymultibak.cz/start", "https://www.mymultibak.cz/start2"], "cliet_ame": "Moje_uiverzali_baka", "cliet_ame#e-us": "My_cool_bak", "logo_uri": "https://www.mybak.cz/logo.pg", "cotact": "ifo@kb.cz", "scopes":[ "pisp", "aisp"] 7
Chybové kódy: HTTP Status Kód Popis 400 ivalid_request Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. 401 ivalid_cliet Nevalidí cliet_id. 401 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 401 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 8
2. Charakteristika resource Iformace o registračích údajích aplikace Zavoláím tohoto resource může TPP požádat o přehled registračích údajů pro kokrétí aplikaci. Pro zavoláí resource je potřeba použít platý certifikát a cliet_id, které je vydáo k tomuto TPP. Výstupem je přehled registračích údajů. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /register/{cliet_id} GET https://api.kb.cz/serverapi/oauth2/v1/register/{cliet_id} request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Příklad requestu: GET https://api.kb.cz/serverapi/oauth2/v1/register/moje_uiverzali_baka- 1234 HTTP/1.1 Accept-Ecodig: gzip, deflate Cotet-Type: applicatio/jso; charset=utf-8 x-request-id: 112233 Host: api.kb.cz Coectio: Keep-Alive Parametry respose: cliet_id strig Y Aplikaci přiřazeé cliet_id. Tímto ID je startová autetizačí proces a dekorováa komuikace při výměě code a refresh_tokeu. cliet_secret strig Y Cliet secret - password/toke vydaý IDP baky pro aplikaci (cliet_id) TPP api_key strig Y API klíč, který aplikace používá při komuikaci s API baky. Pokud baka API klíče epodporuje, vrátí hodotu NOT_PROVIDED applicatio_type web Y Typ aplikace, která bude používat cliet_id. V případě typu web je požadováo defiováí rediect_uris ve formátu webového uri v podobě http/s schéma. redirect_uris Pole obsahující řetězce apř. ve formátu URL Y Výčet URL kam je a koci přesměrováo flow autetizace. Autorizačí request musí obsahovat právě jedo z těchto zaregistrovaých URI v přesém formátu. cliet_ame strig Y Jméo klietské aplikace cliet_ame#e-us strig N Jméo klietské aplikace v příslušém jazyce/kódováí. logo_uri URI N URI loga aplikace (resp. místo odkud je možé ho při registraci stáhout) 9
cotact strig e-mail E-mail jako kotakt a zodpovědou osobu a straě klietské aplikace. scopes Pole strigů Pole aplikací požadovaých scopes. Při registraci jsou scopes validováy proti obsahu použitého certifikátu. Příklad respose bez chyby: HTTP/1.1 200 OK Cotet-Type: applicatio/jso; charset=utf-8 x-request-id: 112233 Host: api.kb.cz Accept-Ecodig: gzip,deflate Cotet-Laguage: cs Cocetio: Keep-Alive { } "cliet_id": "Moje_uiverzali_baka-1234", "cliet_secret": "AAjkk45sd78ad454gddd8712_4555g5g5g5gg", "api_key": "NOT_PROVIDED", "applicatio_type": "web", "redirect_uris": ["https://www.mymultibak.cz/start", "https://www.mymultibak.cz/start2"], "cliet_ame": "Moje_uiverzali_baka", "cliet_ame#e-us": "My_cool_bak", "logo_uri": "https://www.mybak.cz/logo.pg", "cotact": "ifo@mybak.cz", "scopes": ["aisp","pisp"] Chybové kódy: HTTP Status Kód Popis 400 ivalid_request Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. 401 ivalid_cliet Nevalidí cliet_id. 401 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 401 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 10
3. Charakteristika resource Změa registračích údajů Zavoláím tohoto resource může TPP požádat o změu registračích údajů pro kokrétí aplikaci. Pro zavoláí resource je potřeba použít platý certifikát a cliet_id, které je vydáo k tomuto TPP. Výstupem je přehled změěých údajů. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /register/{cliet_id} PUT https://api.kb.cz/serverapi/oauth2/v1/register/{cliet_id} request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Parametry hlavičky (header) requestu: cliet_id strig y Registračí číslo určitého TPP. x-request-id Strig Volitelý parametr pro idetifikaci (spárováí) TPP request / respose Parametry těla (body) requestu: applicatio_type web y Typ aplikace, která bude používat cliet_id. V případě typu web je požadováo defiováí redirect_uris ve formátu webového uri v podobě http/s schéma. redirect_uris Pole obsahující řetězce apř. ve formátu URL [Max 3x 2047 B] y Výčet URL kam je a koci přesměrováo flow autetizace. Autorizačí request musí obsahovat právě jedo z těchto zaregistrovaých URI v přesém formátu. cliet_ame strig [Max 255 B] y Jméo klietské aplikace cliet_ame#e-us strig [Max 1024 B] Jméo klietské aplikace v příslušém jazyce/kódováí. logo_uri URI [Max 2047 B] URI loga aplikace (resp. místo odkud je možé ho při registraci stáhout) cotact strig e-mail [Max 320 B] E-mail jako kotakt a zodpovědou osobu a straě klietské aplikace. scopes Pole strigů [Max 10x 255 B] Pole aplikací požadovaých scopes. Při registraci jsou scopes validováy proti obsahu použitého certifikátu. ["aisp","pisp"] 11
Příklad requestu: POST https://api.kb.cz/serverapi/oauth2/v1/register/moje_uiverzali_baka- 1234 HTTP/1.1 Cotet-Type: applicatio/jso;charset=utf-8 X-request-id: 235144 Host: api.kb.cz Coectio: Keep-Alive Accept-Ecodig: gzip,deflate { } "applicatio_type": "web", "redirect_uris": ["https://www.mymultibak.cz/start", "https://www.mymultibak.cz/start2"], "cliet_ame": "Moje_ejlepsi_baka", "cliet_ame#e-us": "My_best_bak", "logo_uri": "https://www.mybak.cz/logo.pg", "cotact": "ifo@mybak.cz", "scopes": ["aisp"] Parametry hlavičky (header) respose: Cotet-Type strig y Specificatio of required trasfer format. From the precoditio of techical specificatio of this API stadard, i this case, applicatio/jso format is primarily supported. x-request-id Strig Volitelý parametr pro idetifikaci (spárováí) TPP request / respose Parametry těla (body) respose: cliet_id ID aplikace TPP y Jediečý idetifikátor aplikace TPP vydaý bakou, resp IDP baky. Např. použitím resource 0. Iicializačí/registračí resource applicatio_type web y Typ aplikace, která bude používat cliet_id. V případě typu web je požadováo defiováí rediect_uris ve formátu webového uri v podobě http/s schéma. redirect_uris Pole obsahující řetězce apř. ve formátu URL y Výčet URL kam je a koci přesměrováo flow autetizace. Autorizačí request musí obsahovat právě jedo z těchto zaregistrovaých URI v přesém formátu. cliet_ame strig y Jméo klietské aplikace cliet_ame#e-us Libovolý strig Jméo klietské aplikace v příslušém jazyce/kódováí. 12
logo_uri URI URI loga aplikace (resp. místo odkud je možé ho při registraci stáhout) cotact strig e-mail E-mail jako kotakt a zodpovědou osobu a straě klietské aplikace. scopes Pole strigů Pole aplikací požadovaých scopes. Při registraci jsou scopes validováy proti obsahu použitého certifikátu. Příklad respose bez chyby: HTTP/1.1 200 Cotet-Type: applicatio/jso;charset=utf-8 x-request-id: 235144 Host: api.kb.cz Accept-Ecodig: gzip,deflate Cotet-Laguage: cs Coectio: Keep-Alive { } "cliet_id": " Moje_uiverzali_baka-1234", "applicatio_type": "web", "redirect_uris": ["https://www.mymultibak.cz/start", "https://www.mymultibak.cz/start2"], "cliet_ame": "Moje_ejlepsi_baka", "cliet_ame#e-us": "My_best_bak", "logo_uri": "https://www.mybak.cz/logo.pg", "cotact": "ifo@mybak.cz", "scopes": ["aisp"] Chybové kódy: HTTP Status Kód Popis 400 ivalid_request Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. 401 ivalid_cliet Nevalidí cliet_id. 401 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 401 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 400 ivalid_scope Neplatý scope požadavku. 403 isufficiet_scope Např. edostatečé oprávěí pro použití požadovaého scope. 400 ivalid_redirect_uri Hodota jedoho ebo více redirect uri eí validí. 13
4. Charakteristika resource Smazáí aplikace Zavoláím tohoto resource může TPP požádat o smazáí údajů a přístupu kokrétí aplikaci. Pro zavoláí resource je potřeba použít platý certifikát a cliet_id, které je vydáo tomuto TPP. Výstupem je potvrzeí o smazáí. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /register/{cliet_id} DELETE https://api.kb.cz/serverapi/oauth2/v1/register/{cliet_id} request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Příklad requestu: DELETE https://api.kb.cz/serverapi/oauth2/v1/register/moje_uiverzali_baka- 1234 HTTP/1.1 Cotet-Type: applicatio/jso;charset=utf-8 x-request-id:541261 Host: api.kb.cz Coectio: Keep-Alive Accept-Ecodig: gzip,deflate Příklad respose: HTTP/1.1 201 Created x-request-id: 541261 Accept-Ecodig: gzip,deflate Cotet-Laguage: cs Cotet-Type: applicatio/jso;charset=utf-8 Coectio: Keep-Alive Chybové kódy: HTTP Status Kód Popis 401 ivalid_cliet Nevalidí cliet_id. 401 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 401 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 14
5. Charakteristika resource Žádost o ový cliet_secret Zavoláím tohoto resource může TPP požádat o vydáí ového cliet_secret. Pro zavoláí resource je potřeba použít platý certifikát a cliet_id, které je vydáo tomuto TPP. Původí cliet_secret bude tímto requestem zeplatě. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /register/{cliet_id} POST https://api.kb.cz/serverapi/oauth2/v1/register/{cliet_id} request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Příklad requestu: POST https://api.kb.cz/serverapi/oauth2/v1/register/moje_uiverzali_baka- 1234 HTTP/1.1 Cotet-Type: applicatio/jso;charset=utf-8 x-request-id: 245687 Host: api.kb.cz Accept-Ecodig: gzip,deflate Coectio: Keep-Alive Parametry respose: cliet_id strig y Aplikaci přiřazeé cliet_id. Tímto ID je startová autetizačí proces a dekorováa komuikace při výměě code a refresh_tokeu. cliet_secret strig y Cliet secret - password/toke vydaý IDP baky pro aplikaci (cliet_id) TPP Příklad respose bez chyby: HTTP/1.1 200 OK x-request-id: 245687 Host: api.kb.cz Accept-Ecodig: gzip,deflate Cotet-Type: applicatio/jso;charset=utf-8 Coectio: Keep-Alive { } "cliet_id": " Moje_uiverzali_baka-1234", "cliet_secret": "BBjkk45sd78ad454gddd8712_4555g5g5g5gg" Chybové kódy: HTTP Status Kód Popis 400 ivalid_request Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. 401 ivalid_cliet Nevalidí cliet_id. 401 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 15
401 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 16
6. Charakteristika requestu a Autorizačí resource Resource slouží a získaí autorizačího kódu uživatele (code), který je utou podmíkou pro získaí přístupového tokeu. Aplikace třetí stray může zahájit autorizačí proces tím, že přesměruje webový prohlížeč svého uživatele a bakoví autorizačí server. V rámci autorizačího procesu budou od uživatele vyžadováy jeho přihlašovací údaje do iteretového bakovictví KB. Uživateli se po přihlášeí zobrazí výčet povoleí (specifikovaých scopem apř. AISP a/ebo PISP), pro které může udělit souhlas třetí straě. Pokud uživatel povolí aplikaci vybraý přístup, obdrží TPP autorizačí kód jako parametr v rámci přesměrováí a callback URL (adresa uvedeá při registraci aplikace). URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /ssologi GET https://logi.kb.cz/autfe/ssologi request vyžaduje autorizaci uživatele/klieta jako součást voláí API request evyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Parametry requestu: respose_type code y Poviý parametr. Určuje použité autetizačí flow. V tomto případě code grat. Pro autetizačí proces to zameá, že jako výsledek úspěšé idetifikace a autetizace je očekává jedorázový code a místo access_tokeu. cliet_id ID aplikace TPP y Jediečý idetifikátor aplikace TPP vydaý bakou, resp IDP baky. Např. použitím resource 0. Iicializačí/registračí resource redirect_uri URL y URL kam je a koci přesměrováo flow autetizace. Toto URL je staoveo již při vydáí cliet_id a v rámci autetizace je teto parametr validová proti URL zavedeému k cliet_id v systému IDP baky. Hodota by se měla shodovat s jedou z hodot zavedeých použitím resource 0. Iicializačí/registračí resource. scope hodota aisp ebo pisp Atribut pro omezeí požadovaého scope (oprávěí). V případě PSD2 to může být role "aisp ebo "pisp (casesesitive). Pokud se atribut scope euvede vůbec, přebírá se scope z registrovaé aplikace (implicití hodota). Např. pokud je aplikace TPP držitelem obou oprávěí může zde pro svoji kokrétí operaci omezit scope požádat pouze a jedu roli viz. příklad requestu. state Libovolý strig Tímto parametrem je možé obohatit redirect_uri při přesměrováí. Slouží k předáí iformací z aplikace přes autetizačí flow. (může sloužit i pro spárováí request/respose dotazu) Příklad requestu: GET https://logi.kb.cz/autfe/ssologi HTTP/1.1 Host: logi.kb.cz Cotet-Type: applicatio/x-www-form-urlecoded cliet_id=moje_uiverzali_baka-1234& redirect_uri=https://www.mymultibak.cz/start& respose_type=code& scope=aisp& state=12345678 17
Příklad voláí přes příkazovou řádku prohlížeče (zde pouze pro scope AISP) V liku https://logi.kb.cz/autfe/ssologi?respose_type=code&cliet_id=doplnit_cliet_id&redirect_uri=doplnit_redirect_ uri&state=12345678&scope=aisp Hodoty barevých částí (cliet_id, redirect_uri) je uté doplit. Atribut scope eí uté uvádět vůbec, přebere se scope aplikace v plém rozsahu (aisp a pisp). Pro omezeí požadovaého rozsahu scope, lze uvést pouze jedu z hodot aisp ebo pisp (více hodot eí přípustých). 18
Parametry respose: Pole Popis code state Autorizačí code (typu JWT toke skládající se ze 3 částí odděleých tečkou) Parametr state z requestu TPP Příklad respose bez chyby: cotet-type: applicatio/x-www-form-urlecoded date: Wed, 8 Mar 2017 20:56:28 GMT locatio: https://www.mymultibak.cz/start? code=a200234062baa2ada828bbd33c1f6054& state=12345678 status: 302 Chybové kódy: HTTP Status Kód Popis 302 ivalid_request Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. 302 uauthorized_cliet Kliet eí oprávěý provádět teto dotaz. 302 access_deied Autorizačí server odmítl přístup. 500, 503 server_error Chyba autorizačího serveru. 302 ivalid_scope Neplatý scope požadavku. Příklad error respose: HTTP/1.1 302 Foud Locatio: https://www.mymultibak.com/logi? error=ivalid_request &error_descriptio=usupported%20respose_uri &state=logi_cz 19
7. Charakteristika requestu Získáí/vystaveí tokeu Poté co vaše aplikace obdrží autorizačí kód, může ho ásledě vyměit za access ebo refresh toke. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /toke POST https://api.kb.cz/serverapi/oauth2/v1/toke request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Parametry requestu: code strig (pokud se jedá o získáí access tokeu pak je poviý) refresh_toke strig (pokud se jedá o oboveí access tokeu pak je poviý) Autorizačí kód vráceý z původího requestu. Řetězec refrešovacího tokeu.. grat_type strig y Validí hodoty autorizačího kódu Povoleé hodoty : authorizatio_code, refresh_toke redirect_uri strig (pokud se jedá o získáí access tokeu pak je poviý) cliet_id (pokud se jedá o získáí access tokeu pak je poviý) cliet_secret strig (pokud se jedá o získáí access tokeu pak je poviý) Autorizačí kód bude zaslá a toto URL jako parametr. Musí se shodovat s jedím URL zaregistrovaým během registrace aplikace. Hodota je defaultě astavea a prví URl, které bylo klietovi akofigurováo. Cliet_ID je získáo během registrace aplikace, ID aplikace TPP. Cliet secret - password/toke vydaý IDP baky pro aplikaci (cliet_id) TPP x-request-id Strig Volitelý parametr pro idetifikaci (spárováí) TPP request / respose 20
Příklad requestu: POST https://api.kb.cz/serverapi/oauth2/v1/toke HTTP/1.1 Host: api.kb.cz Cotet-Type: applicatio/x-www-form-urlecoded x-request-id: 548795 code=a200234062baa2ada828bbd33c1f6054& cliet_id=moje_uiverzali_baka-1234& cliet_secret=bbjkk45sd78ad454gddd8712_4555g5g5g5gg& redirect_uri=https://www.mymultibak.cz/start& grat_type=authorizatio_code Parametry respose: toke_type strig y Typ zadaého tokeu. Hodota erozlišuje velká písmea. Typ tokeu apříklad Bearer access_toke strig y Přístupový toke vydaý autorizačím serverem. refresh_toke strig Refreshovací tokey jsou pověřeí užívaá k obstaráí ových přístupových tokeů když už byly autorizováy. expires_i iteger($it64) y Životost přístupového tokeu, uvádí se v sekudách. scope strig y Scope vystaveého JWT tokeu apř. aisp, pisp Příklad respose bez chyby: Úspěšě zpracovaý request odpoví respose s takto defiovaým JSON payloadem: { } "scope": "aisp pisp", "expires_i": 3600, "toke_type": "Bearer", "access_toke": "ae9eef9b0af42c674d0b1c1128c37c2d" "refresh_toke": "be9eef9b0af42c674d0b1c1128c37c2g" Chybové kódy: HTTP Status Kód Popis 400 ivalid_request ivalid_cliet ivalid_grat uauthorized_cliet Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. Nevalidí uživatel. Neplaté pověřeí. Uživatel eí oprávěý používat autorizačí typ. 401 Access_deied Přístup odepře 403 Forbidde Kliet eí oprávěý provádět teto dotaz. 404 Not foud Zadaý dotaz se epodařilo ajít 429 Too may requests Kapacita systému byla překročea zadáím přílišého možství requestů. 500 Iteral server error Chyba serveru 21
8. Charakteristika requestu Zeplatěí tokeu API sloužící ke zrušeí platosti refresh ebo access tokeu. URI: HTTP Metoda: Request URL: Authorizatio: Certificatio: /revoke POST https://api.kb.cz/serverapi/oauth2/v1/revoke request vyžaduje autorizaci uživatele/klieta jako součást voláí API request vyžaduje použití kvalifikovaého certifikátu třetí stray. Podporovaé kódováí: charset=utf-8 Parametry requestu: Parametr Toke Popis OAuth2 access ebo refresh toke získaý a základě autetizačího procesu po výměě za code resp. refresh toke (v případě access_tokeu) Příklad requestu: POST https://api.kb.cz/serverapi/oauth2/v1/revoke HTTP/1.1 Host: api.kb.cz x-request-id: 897145 Cotet-Type: applicatio/x-www-form-urlecoded Coectio: Keep-Alive toke=be9eef9b0af42c674d0b1c1128c37c2g&cliet_id=moje_uiverzali_baka-1234& cliet_secret=bbjkk45sd78ad454gddd8712_4555g5g5g5g Chybové kódy: HTTP Status Kód Popis 302 Ivalid_request Ivalid_cliet Access_deied 400 ivalid_request Ivalid_cliet TODO validace s CAAS, přebírame 401 Ivalid_grat Ivalid_toke Nevalidí request ebo evalidí kliet, přístup odepře. Nevalidí request. V dotazu chybí povié pole ebo je v evhodém / evalidím formátu. Nevalidí kliet, evalidí oprávěí ebo evalidí toke. 403 Forbidde Kliet eí oprávěý provádět teto dotaz. 404 Not foud Zadaý dotaz se epodařilo ajít 429 Too may requests Kapacita systému byla překročea zadáím přílišého možství requestů. 500 Iteral server error Chyba serveru 22