Bank backend

This document describes how a bank’s backend should call Dateio Platform API services to fulfil the needs of Dateio SDK. Both test and production environments are described.

Dateio Platform API accepts only REST API calls, access through a web browser is not possible.

Overall architecture

SDK calls bank’s backend API and not directly Dateio Platform API. This is for security and monitoring reasons, since bank mobile applications are usually using a token (e.g. JWT) linked to an individual client or other sensitive information. This token should not be exposed to a 3rd party, since it could be theoretically exploited to act on client behalf. Also Dateio and Bank need a common X‑client‑id to identify the client across API calls, cards linked to client, transactions, and cashback payout. Dateio is not able to extract this client id from token and it is not desirable to send this as plain id directly from mobile application. Last but not least with this solution bank can monitor and log requests, traffic and others program metrics.

The bank backend API itself will be directly communicating with Dateio Platform API. Dateio prefer that bank backend just pass requests from SDK to Dateio Platform API, add header to requests which will be identifying user – see X‑client‑id, authenticate against Dateio backend (see next chapter) and remove all sensitive headers, e.g., that with user token.

It is up to bank decision if bank backend will be standalone system or it will be added to existing more complex one. SDK contains method that sets endpoint that all communication will be sent to. For bank backend demo see demos section. It contain simple API gateway written in Kotlin, that shows what functions Dateio need from bank backend.

Authentication

API is secured with OAuth 2.0 authentication. At first bank’s backend must obtain authorization token via following request:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "client_id=<bank id>"
-d "client_secret=<client secret>" -d "grant_type=client_credentials"
'https://<url>/auth/realms/<realm>/protocol/openid-connect/token'

Where:

client secret and bank id is provided upon request via secured channel.
url URL that you will get from Dateio. Not stated for security reasons.
realm = fo-uat for UAT environment, fo-prod for PROD environment.

Then you can call Dateio Platform API. You have to obtain a new token when the current one is expired.

Make sure to reuse this token for all requests to the Dateio Platform API until it expires. Request a new one only after the old token expires or is about to expire. Generating a new token for every request is not a desired use case and will lead to your backend being blocked.

Dateio Platform API requests

The bank’s backend should resend every request it receives to Dateio Platform API – including all headers added by SDK, except user token and other sensitive headers, if added.

Before resending request to Dateio, following headers must be added:

X-client-id – client ID known to Dateio. Should be deduced based on user token send from mobile app.
Authorization – authorization token obtained via Authentication.

When returning response to SDK, please make sure to add these headers and values:

cache-control – "no-cache, no-store, max-age=0, must-revalidate"
pragma – "no-cache"

Health-check

To check Dateio’s API availability you can use the following request:

curl -i -X GET  -H "Authorization:Bearer <auth token>  'https://<url>/health-check'

You will get url from Dateio. Not stated for security reasons. Health-check is available for both UAT and PROD environments. HTTP status 200 means Dateio Platform API is available.

You can also use https://status.dateio.eu to check API and SFTP availability.

Environments

UAT environment

You will get uat-url from Dateio. Not stated for security reasons. Dateio provides only one development environment, but you might connect multiple bank environments to it, if necessary. Make sure that you don't duplicate users id between them.
For auth token see Authentication section.

Example of a curl query:

curl -i -k -X GET  -H "Accept:application/json"  -H "Content-Type:application/json"  -H "Accept-Version:29"
 -H "X-Client-Id:8435329"  -H "Authorization:Bearer <auth token>" 'https://<uat-url>/offers'

PROD environment

You will get prod-url from Dateio. Not stated for security reasons. For auth token see Authentication section.

Example of a curl query:

curl -i -k -X GET  -H "Accept:application/json"  -H "Content-Type:application/json"  -H "Accept-Version:29"
 -H "X-Client-Id:1"  -H "Authorization:Bearer <auth token>" 'https://<prod-url>/offers'

Where to head next

You can continue to specific platform implementation.