API Authorization

finAPI uses KeyCloak for authorizing to Demobank. To access an API endpoint an access token (jwt) token is required. KeyCloak can be used to create this access token. Also, KeyCloak can be used to refresh the access token. Currently the access token expires after 15 minutes.

For the authorization the following parameter are needed:

KeyCloak URL parameter:

mandator: <obtained from finAPI>

Request parameter:

username: <obtained from finAPI>
password: <obtained from finAPI>
client_id: demobank-cli (fixed)
grant_type: password (fixed)

KeyCloak URL

POST https://keycloak-finapi-general-live.finapi.io/realms/<mandator>/protocol/openid-connect/token

NOTE: Replace the <mandator> parameter within the URL with the data you obtained from finAPI

Example request:

CODE

 curl --location 'https://keycloak-finapi-general-live.finapi.io/realms/customer/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=demobank-cli' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<user password>' \
--data-urlencode 'grant_type=password'

NOTE: The Content-Type of the request must be set to 'application/x-www-form-urlencoded'

If the given parameters are valid, KeyCloak will respond with the authorization data.
Here is an example of a response when authorizing a user:

CODE

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkf6Hk4speaF...",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5N...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "4a273b32-cc81-bbb3-bbc3-636d2c0d759d",
    "scope": "xs2a_mock:user profile",
    "mandator_name": "finAPI Demobank",
    "mandator_uuid": "044ab580-XXXXXXXXXXXXX-991e324704b7",
    "is_test_mandator": "false",
    "is_technical_user": "false"
}

Use the returned access_token token for other service calls by sending it in a 'Authorization' header, with the word 'Bearer' in front of the token.

Example:

CODE

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkf6Hk4speaF...

By default, the access tokens has an expiration time of 15 minutes. If a token has expired, then using the token for a service call will result in a HTTP code 401. To restore access token you can simply get a new token (as it is described above) or use grant_type=refresh_token. In this case you just have to pass the previously received refresh_token for the user.

Example:

CODE

curl --location 'https://keycloak-finapi-general-live.finapi.io/realms/customer/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=demobank-cli' \
--data-urlencode 'refresh_token=eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5N...' \
--data-urlencode 'grant_type=refresh_token'