API OAUTH2 Sandbox SK Manual - kb.cz

1

API OAUTH2

Sandbox SK Manual

2

Change log

Date Version Description

29.01.2020 1 First document version

01.06.2020 2 Document edit

3

Contents API OAUTH2 .................................................................................................................................................................... 1 Sandbox SK Manual ........................................................................................................................................................ 1 Error reporting .................................................................................................................................................................. 4 Procedure of Generating the authorization_code/refresh Token for the Application ........................................................ 4

1.1 Prerequisites of access to applications ............................................................................................................... 4 1.2 Entering the application menu ............................................................................................................................. 4 1.3 Viewing the application ....................................................................................................................................... 5 1.4 Sandbox keys...................................................................................................................................................... 6 1.5 Storing the Consumer Key and Consumer Secret .............................................................................................. 7 1.6 Preconditions for generating the authorization_code/refresh token .................................................................... 9 1.7 Entering the callback URL ................................................................................................................................... 9 1.8 Modifying the identity server link ....................................................................................................................... 10 1.9 Access to the identity server ............................................................................................................................. 11 1.10 Signing in ...................................................................................................................................................... 12 1.11 Obtaining the code ........................................................................................................................................ 12 1.12 API menu ...................................................................................................................................................... 13 1.13 Selecting the API OAUTH2 ........................................................................................................................... 13 1.14 Entering the OAUTH2 API ............................................................................................................................ 14 1.15 Selecting the “/token” operation .................................................................................................................... 15 1.16 Filling in the required fields ........................................................................................................................... 15 1.17 “/token” operation error message .................................................................................................................. 17 1.18 Selecting the “/revoke” operation for testing ................................................................................................. 18 1.19 Filling in the required fields of the “/revoke” operation .................................................................................. 18 1.20 “/revoke” operation error message ................................................................................................................ 19

2 Access to the application through direct calling ..................................................................................................... 21 2.1 Initializing/Registering Resource Characteristics .............................................................................................. 21 2.2 Information on Application Registering Data – Resource Characteristics ......................................................... 25 2.3 Changing the Registering Data – Resource Characteristics ............................................................................. 27 2.4 Deleting the Application – Resource Characteristics ......................................................................................... 30 2.5 Requesting a New client_secret – Resource Characteristics ............................................................................ 31 2.6 Obtaining/Issuing the Token – Request Characteristics .................................................................................... 32 2.7 Invalidating the Token – Request Characteristics ............................................................................................. 34 2.8 Authorising Resource – Request Characteristics .............................................................................................. 35

4

Error reporting

Reporting quarantined errors or calling them always takes place via the mailbox [email protected]. The e-mail sent must contain the following information, in case the required information is missing, it will not be possible to process the query or error.

PSD2 API: CZ, SK Environment: Sandbox, Production Whether it was called from FE Sandbox incl. the type and version of the browser used or, in the case of a BE call, the name and version of the program for the BE call Request type Date and time of the call IP address The error and its most accurate description, which can be supplemented with the appropriate screenshot Without the above values, it is not possible to solve the reported error.

Procedure of Generating the authorization_code/refresh Token for the Application

1.1 Prerequisites of access to applications

The user must be properly registered (see Section Chyba! Nenalezen zdroj odkazů.) and signed in (see Section Chyba! Nenalezen zdroj odkazů.). viz. manual Sandbox SK registration

1.2 Entering the application menu

By clicking on the “Applications” button in the upper part of the screen, the signed-in user can enter the menu to register his/her application.

5

1.3 Viewing the application

The user clicks on the “View” option to display the preview of the selected operation. The function consists of 3 main parts: DETAILS, SUBSCRIPTION, and SANDBOX KEYS.

6

1.4 Sandbox keys

Subsequently, the user goes to the “Sandbox keys” section. If the conditions for generating the authorization_code/refresh token are met (see Section 0), the user can generate here a key/token securing access to a given scope and for the token as such (e.g. AISP, PISP, etc.) with properties set by the user here and with grant types selected by him/her.

7

1.5 Storing the Consumer Key and Consumer Secret

The signed-in user can copy (for example to Notepad) the values from the “Consumer Key” and “Consumer Secret” fields (e.g. to the Notepad).

8

9

1.6 Preconditions for generating the authorization_code/refresh token

If the authorization_code/refresh token should be generated for a specific application, an API must be subscribed for this application, which makes it possible and uses this operation (e.g. AISP, PISP, etc.).

1.7 Entering the callback URL

10

The user enters the value https://www.koba.sk into the “Callback URL” text field in the “Grant Types” section and subsequently checks the “Code” checkbox. Then the user clicks on the “UPDATE” button.

1.8 Modifying the identity server link

Further, the user will change the string that follows client_id to the copied consumer key (the character “&” is not part of client_id) taken from the Sandbox Keys section of the given application. This is done in the following link:

11

https://api.kb.cz/sandbox/authfe?scope=aisp&redirect_uri=https://www.koba.sk&client_id=2dXmYO_yyYwLHW0yyaaCXTiAUy4a&state=123456&response_type=code

1.9 Access to the identity server

The user opens an anonymous window in any browser and enters the address modified in the manner described in the foregoing paragraph.

12

1.10 Signing in

When the foregoing step is completed, the sign-in screen is displayed. Use your credentials for Sandbox.

1.11 Obtaining the code

Now the user is redirected to the next page. The URL of this page contains the code value, which will later be used for generating the token.

13

1.12 API menu

Subsequently, the user clicks on the “APIs” button in the upper part of the screen to enter the menu containing all APIs he/she is allowed to access.

1.13 Selecting the API OAUTH2

The user can display the specific API by clicking on “VIEW MORE”.

14

1.14 Entering the OAUTH2 API

API CONSOLE – a list of operations allowed by the specific API; DOCUMENTATION – all available documentation concerning the specific application. The subscription of a selected API can be made here by clicking on the “SUBSCRIBE” button, so that the given applications can use the API’s functions (as long as the user is properly signed in).

15

1.15 Selecting the “/token” operation

The user then goes to the “API CONSOLE” section and selects the “/token” operation to generate the access token or refresh token.

1.16 Filling in the required fields

The user wishing to get the access token generated fills in all mandatory fields with values in an appropriate format. The user will enter the code found in the URL in step 1.11 to the “code” field; the redirect_uri insert https://koba.sk ;the consumer key stored in step 0 to the “client_id” field; and the consumer secret stored in step 0 to the pole “client_secret” field. If everything is done properly, the specific token will be generated after pressing the "TRY IT OUT" button.

https://koba.sk/

16

17

1.17 “/token” operation error message

If any value has been entered incorrectly, one of the following error messages will be displayed after pressing the "TRY IT OUT" button, otherwise the result statement will be displayed.

18

1.18 Selecting the “/revoke” operation for testing

The user chooses an operation he/she wishes to test. In this case, it is “/revoke”. The user can cancel the existing refresh token or access token using this operation.

1.19 Filling in the required fields of the “/revoke” operation

19

The user wishing to cancel an existing token fills in all mandatory fields with values in an appropriate format. If everything is done properly, the specific token will be cancelled. If any of mandatory fields is not filled in, the report is not displayed and the blank fields are highlighted in red.

1.20 “/revoke” operation error message

20

If any value has been entered incorrectly, one of the following error messages will be displayed after pressing the "TRY IT OUT" button, otherwise the result statement will be displayed.

21

2 Access to the application through direct calling

2.1 Initializing/Registering Resource Characteristics

By calling this resource, the TPP can ask for the dynamic registration of the client_id. A valid certificate should be used to call the resource. The client_id and client_secret parameters are the outputs that the TPP needs to start and go through the user (bank client) authentication process. The API_Key, which is the bearer of the application configuration during the bank API calling, is another output. URI: /register HTTP Method: POST

Request URL: https://api.koba.sk/sandbox/oauth2/v1/register

Authorization: the request requires the user/client authorisation as part of the API calling Certification: the request requires the use of the third party qualified certificate.

Supported encoding: charset=UTF-8 Request header parameters:

Parameter Values Mandatory Description

Tpp_id string

y Registration number of the particular TPP.

Request body parameters:


application_type web, native

y A type of the application using client_id. The web type

requires defining the rediect_uris in the web uri format,

in the form of http/s scheme. The native type allows

for inputting e.g. an application package or own format

in redirect_uris.

redirect_uris Field containing

strings, e.g. in the

URL format

[Max 3x 2047

B]

y A listing of URL to which the flow authentication is

redirected in the end. The authorizing request must

contain exactly one of those registered URI in a precise

format.

client_name string

[Max 255 B]

y The client application name.

client_name#en-US string

[Max 1024 B]

n The client application name in the relevant language

or encoding.

logo_uri URI

[Max 2047 B]

n The application logo URI (or the location from which it

can be downloaded during registering)

contact string e-mail

[Max 320 B]

n A contact E-mail to a competent person on the side of

the client application.

scope Pole stringů

[Max 10x 255

B]

n A field of scopes required by the application. The

scopes are validated against the contents of the used

certificate during registering.

https://api.koba.sk/sandbox/oauth2/v1/register

22

Example of a request:

POST /oauth2/register HTTP/1.1

Content-Type: application/json

Accept: application/json

Host: idp.banka.cz

{

"application_type": "web",

"redirect_uris":

["https://www.mymultibank.cz/start",

"https://www.mymultibank.cz/start2"],

"client_name": "Moje univerzální banka",

"client_name#en-US": "My cool bank",

"logo_uri": "https://www.mybank.cz/logo.png",

"contact": "[email protected]",

"scopes": ["aisp", "pisp"]

}

Response header parameters:


Content-Type string

y A specification of the required transfer format. Based on

the prerequisites of the technical specification of this API

standard, in this case the application/json format is

primarily supported.

Response body parameters:

Parameter Values Mandato

ry

Description

client_id string

y The client_id assigned to the application. This ID

launches the authentication process and decorates

communication during the exchange of the code and

refresh_token.

client_secret string y Client secret – a password/token issued by the bank IDP

for the (client_id) TPP application.

client_secret_expire

s_at

Time n The default value is 0 (client_id never expires).

Otherwise, the field contains a value in seconds

expressing the period of time that has elapsed from

1970-01-01T0:0:0Z.

api_key string y The API key used by the application when

communicating with the bank API. If the given bank does

not support API keys, the field returns

“NOT_PROVIDED”.



requires defining the rediect_uris in the web uri format, in

the form of http/s scheme. The native type allows for

inputting e.g. an application package or own format in

redirect_uris.

23

redirect_uris Pole obsahující

řetězce např. ve

formátu URL

[Max 3x 2047 B]




format.

client_name string

[Max 255 B]



[Max 1024 B]

n The client application name in the relevant language or

encoding.

logo_uri URI

[Max 2047 B]


can be downloaded during registering).

contact string e-mail

[Max 320 B]

n A contact E-mail to a competent person on the part of the

client application.

scopes Pole stringů

[Max 10x 255 B]

n A field of scopes required by the application. The scopes

are validated against the contents of the used certificate

during registering.

Example of an error-free response:

HTTP/1.1 201 Created


Cache-Control: no-store

Pragma: no-cache

{

"client_id": "a0b25291f0",

"client_secret":

"AAjkk45sd78ad454gddd8712_4555g5g5g5gg",

"client_secret_expires_at": 0,

"api_key":

"00000000-1212-0f0f-a0a0-123456789abc",


"redirect_uris":






Error codes:

24

HTTP Status Code Description

400 invalid_request Invalid request. It is missing a mandatory field or its format is

inappropriate / invalid.

401 invalid_client Invalid client_id.

401 unauthorized_client The client is not authorised to execute this query.

401 access_denied Access denied by the authorising server.

500, 503 server_error Authorising server error.

25

2.2 Information on Application Registering Data – Resource Characteristics

By calling this resource, the TPP may ask for an overview of the registering data related to a particular application. To call the resource, a valid certificate and client_id issued for this TPP should be used. An overview of the registering data is the output. URI: /register/{client_id} HTTP Method: GET

Request URL: https://api.koba.sk/sandbox/oauth2/v1/register/{client_id} Authorization: the request requires the user/client authorisation as part of the API calling Certification: the request requires the use of the third party qualified certificate.

Supported encoding: charset=UTF-8 Example of a request:

GET /oauth2/register/a0b25291f0 HTTP/1.1



Host: idp.banka.cz

Response parameters:


client_id string




refresh_token.

client_secret string y Client secret – a password/token issued by the bank IDP for

the (client_id) TPP application.


s_at


Otherwise, the field contains a value in seconds expressing

the period of time that has elapsed from 1970-01-01T0:0:0Z.

api_key string y The API key used by the application when communicating

with the bank API. If the given bank does not support API

keys, the field returns “NOT_PROVIDED”.



requires defining the rediect_uris in the web uri format, in the

form of http/s scheme. The native type allows for inputting

e.g. an application package or own format in redirect_uris.

redirect_uris Field

containing

strings, e.g. in

the URL

format

y A listing of URL to which the flow authentication is redirected

in the end. The authorizing request must contain exactly one

of those registered URI in a precise format.

client_name string y The client application name.

client_name#en-US string n The client application name in the relevant language or

encoding.

logo_uri URI n The application logo URI (or the location from which it can

be downloaded during registering).

https://api.koba.sk/sandbox/oauth2/v1/register/%7bclient_id%7d

26

contact string e-mail n A contact E-mail to a competent person on the part of the

client application.

scopes Pole stringů n A field of scopes required by the application. The scopes are

validated against the contents of the used certificate during

registering.


HTTP/1.1 200 OK


{


"client_secret":

"AAjkk45sd78ad454gddd8712_4555g5g5g5gg",


"api_key":

"00000000-1212-0f0f-a0a0-123456789abc",


"redirect_uris":








}

Error codes:








27

2.3 Changing the Registering Data – Resource Characteristics

By calling this resource, the TPP may ask for changing the registering data related to a particular application. To call the resource, a valid certificate and client_id issued for this TPP should be used. An overview of the changed data is the output. URI: /register/{client_id} HTTP Method: PUT


Supported encoding: charset=UTF-8 Request header parameters:


client_id string

y Registration number of the particular TPP.

Request body parameters:




requires defining the redirect_uris in the web uri format,

in the form of http/s scheme. The native type allows for


redirect_uris.



URL format

[Max 3x 2047

B]




format.

client_name string

[Max 255 B]



[Max 1024 B]

n The client application name in the relevant language or

encoding.

logo_uri URI

[Max 2047 B]



contact E-mail string

[Max 320 B]

n A contact E-mail to a competent person on the part of the

client application.

scopes String field

[Max 10x 255

B]

n A field of scopes required by the application. The scopes


during registering. [ aisp, pisp ]


28


POST /oauth2/register/a0b25291f0 HTTP/1.1



Host: idp.banka.cz

{


"redirect_uris":








}

Response header parameters:


Content-Type string

y A specification of the required transfer format. From the

precondition of technical specification of this API

standard, in this case, application/json format is

primarily supported.

Response body parameters:


client_id ID TPP of

application

y A unique identifier of the TPP application issued by the

bank, or the bank IDP, e.g., by using the “0.

Initializing/registering resource”.


s_at


Otherwise, the field contains a value in seconds

expressing the period of time that has elapsed from

1970-01-01T0:0:0Z.


y

A type of the application using client_id. The web type

requires defining the rediect_uris in the web uri format, in

the form of http/s scheme. The native type allows for


redirect_uris.



URL format




format.

client_name string y The client application name.

client_name#en-US Arbitrary string n The client application name in the relevant language or

encoding.

logo_uri URI n The application logo URI (or the location from which it


29

contact E-mail string n A contact E-mail to a competent person on the part of the

client application.

scopes String field n A field of scopes required by the application. The scopes


during registering.


HTTP/1.1 200


{




"redirect_uris":








}

Error codes:








400 invalid_scope Invalid request scope.

403 insufficient_scope E.g. insufficient authorisation to use the required scope.

400 invalid_redirect_uri The value(s) of one or more redirect uris is/are not valid.

30

2.4 Deleting the Application – Resource Characteristics

By calling this resource, the TPP may ask for deleting data and access to a particular application. To call the resource, a valid certificate and client_id issued for this TPP should be used. A confirmation of the deletion is the output. URI: /register/{client_id} HTTP Method: DELETE



DELETE /oauth2/register/a0b25291f0 HTTP/1.1



Host: idp.banka.cz

Example of a response:

HTTP/1.1 201 Created

Error codes:







31

2.5 Requesting a New client_secret – Resource Characteristics

By calling this resource, the TPP may ask for issuing a new client_secret. To call the resource, a valid certificate and client_id issued for this TPP should be used. The previous client_secret will be invalidated by this request. URI: /register/{client_id} HTTP Method: POST



POST /oauth2/register/a0b25291f0/renewSecret HTTP/1.1



Host: idp.banka.cz



client_id string




refresh_token.

client_secret string y Client secret – a password/token issued by the bank IDP for

the (client_id) TPP application.


s_at


Otherwise, the field contains a value in seconds expressing

the period of time that has elapsed from 1970-01-01T0:0:0Z.


HTTP/1.1 200 OK

{


"client_secret": "BBjkk45sd78ad454gddd8712_4555g5g5g5gg",

"client_secret_expires_at": 0

}

Error codes:









32

2.6 Obtaining/Issuing the Token – Request Characteristics

Having received the authorisation code, your application may subsequently swap it for an access token or refresh token. URI: /token HTTP Method: POST

Request URL: https://api.koba.sk/sandbox/oauth2/v1/token


Supported encoding: charset=UTF-8 Request parameters:


code string

n

(mandatory

in the case

of obtaining

the access

token)

An authorisation code returned from the original request.

refresh_token string

n

(mandatory

in the case

of

refreshing

the access

token)

A refresh token string.

grant_type string

y Valid values of the authorisation code.

Permitted values of authorization_code, refresh_token.

redirect_uri string

n

(mandatory

in the case

of obtaining

the access

token)

The authorisation code will be sent to this URL as a

parameter. It should be identical to one URL registered

during the application registering. By default, the value is

set to the first URl that has been configured for the client.

client_id n

(mandatory

in the case

of obtaining

the access

token)

The Client_ID is obtained while the application is being

registered, TPP application ID.

client_secret string

n

(mandatory

in the case

of obtaining

the access

token)

Client secret – a password/token issued by the bank IDP

for the (client_id) TPP application.

https://api.koba.sk/sandbox/oauth2/v1/token

33

Example of a request: POST /oauth2/token HTTP/1.1

Host: idp.banka.cz

Content-Type: application/x-www-form-urlencoded

code=a200234062baa2ada828bbd33c1f6054&

client_id=MyPFM&

client_secret={client_secret}&

redirect_uri=https://www.mypfm.cz/start&

grant_type=authorization_code



token_type string y The inputted token type. The value does not distinguish

between capital and lower-case letters. An example of

the token type: “Bearer”

access_token string y

An access token issued by the authorising server.

refresh_token string n Refresh tokens are authorisations used for obtaining new

access tokens after they have been authorised.

expires_in integer($int64) y A life time of the access token expressed in seconds.

acr integer($int64) n The authentication security level. The value van range

from 0 to 4, the default value is 3. “0” means nonSCA.


A successfully processed request generates a response with the JSON payload defined as follows: {

"expires_in": 3600,

"token_type": "Bearer",

"access_token": "ae9eef9b0af42c674d0b1c1128c37c2d"

"refresh_token": "be9eef9b0af42c674d0b1c1128c37c2g",

"acr": "0"

}

Error codes:




401 Unauthorized_client

Access_denied

Erroneous client-side authorisation, access denied.

403 Forbidden The client is not authorised to execute this query.

404 Not found The entered query has not been found.

429 Too many requests The system capacity has been exceeded by inputting too many

requests.

500 Internal server error Server error.

34

2.7 Invalidating the Token – Request Characteristics

The API invalidating the refresh token or access token. URI: /revoke HTTP Method: POST

Request URL: https://api.koba.sk/sandbox/oauth2/v1/revoke



Parameter Description

token OAuth2 access or refresh token obtained during the authentication process after its exchange

(swap) for the code or refresh token (in the case of the access_token).

Example of a request: POST /oauth2/revoke HTTP/1.1

Host: idp.banka.cz


token=be9eef9b0af42c674d0b1c1128c37c2g

Error codes:


302 Invalid_request

Invalid_client

Access_denied

Invalid request or invalid client; access denied.



401 Invalid_client

Invalid_grant

Invalid_token

Invalid client, invalid grant, or invalid token.

403 Forbidden The client is not authorised to execute this query.

404 Not found The entered query has not been found.

429 Too many requests The system capacity has been exceeded by inputting too many

requests.

500 Internal server error Server error.

https://api.koba.sk/sandbox/oauth2/v1/revoke

35

2.8 Authorising Resource – Request Characteristics

If your client/application has not been authorised, it must obtain an authorising code before applying for an access token. Your application may launch the authorising process by redirecting its user’s web browser to the bank authorisation server. The server will then require user’s data from the user. Authorisations specified by the scope and a list of bank services and payment services from which to choose will be displayed to the user. If the user makes it possible for your application to access any of them, the server will send an authorising code to the callback URL by redirecting the browser to redirect_uri. URI: /ssologin HTTP Method: GET

Request URL: https://api.koba.sk/sandbox/oauth2/autfe/ssologin Authorization: the request requires the user/client authorisation as part of the API calling Certification: the request does not require the use of the third party qualified certificate.



response_type code y A mandatory parameter determining the authentication flow

that has been used (code grant in this case). In terms of the

authentication process it means that a one-time code is

expected instead of the access_token as a result of a

successful identification and authentication.

client_id ID of TPP

application

y A unique identifier of the TPP application issued by the bank,

or the bank IDP, e.g., by using the “0. Initializing/registering

resource”.

redirect_uri URL y An URL to which the authentication flow is redirected in the

end. This URL is already determined while the client_id is

issued, and this parameter is validated as part of the

authentication against the URL introduced for the client_id on

the bank’s IDP system. The value should be identical to one

of the values introduced by using the “0. Initializing/registering

resource”.

scope List of

authoris-

ations

separated by

a space

n A field of scopes (authorisations) required by the application.

For PSD2, it may be the aisp and pisp roles. E.g., if the TPP

is a holder of both authorisations, it may require here either

one or both for its application (see the example of the request).

state Arbitrary

string

n Redirect_uri can be supplemented with this parameter when

redirected. It conveys information from the application via the

authentication flow.


GET /oauth2/authfe/ssologin HTTP/1.1 Host: idp.banka.cz


client_id=MyPFM&

redirect_uri=https://www.mypfm.cz/start&

response_type=code&

scope=aisp pisp&

state=balance

https://api.koba.sk/sandbox/oauth2/autfe/ssologin

36


Pole Description

code Authorisation code

state A state parameter from the TPP request.

Example of an error-free response: content-type: application/x-www-form-urlencoded

date: Wed, 8 Mar 2017 20:56:28 GMT

location: https://www.mypfm.cz/start?

code=a200234062baa2ada828bbd33c1f6054&

state=balance

status: 302

Error codes:







302 invalid_scope Invalid request scope.

Example of an error response: HTTP/1.1 302 Found

Location: https://www.mymultibank.com/login?

error=invalid_request

&error_description=Unsupported%20response_uri

&state=login_cz

Documents

API OAUTH2 Sandbox SK Manual - kb.cz