Central Concepts

Authentication

Authentication is important, but in our Quick Start Guide we minimize coverage of authentication details so you can focus on your core requirements and address authentication later.

With BANKS/Connect, there are three authentication methods:

• Authentication as a client using an OAuth 2.0 client token.
• Authentication as a user using an OAuth 2.0 user token.
• Authentication with the bank or service provider using encrypted provider credentials.

Additionally, the BANKSapi Auth API includes an admin client that you can use to create and manage users.

The authentication method required for each operation is specified in the corresponding sub-API documentation. As a general rule, all requests to BANKS/Connect are made in the context of a client, which is sufficient for operations like querying providers. Other operations require a user token and appropriate bank access consents.

Bank

In BANKS/Connect, the institutions from which we collect data on your behalf are referred to as "banks". Banks and service providers are collectively called Providers.

The banks activated for you in BANKS/Connect can be accessed via the BANKS/Connect Providers API.

User

The unique user is the primary billing unit. Additional details are defined in your service agreement.

A user encompasses all data retrieved about a person from various banks or service providers.

With BANKS/Connect, users belong to you, the client. Access to the financial data of your users is provided via the BANKS/Connect Customer API.

With the BANKS/Connect Auth API, you can manage your users.

Client

We use the term client to refer to both your application(s) and an "admin client" for managing users. From our perspective, a client is a set of access credentials for BANKS/Connect.

Using a client ID, you can obtain client tokens via the BANKS/Connect Auth API using OAuth2. These tokens can then be used to access functions in the BANKS/Connect Customer API and the BANKS/Connect Providers API.

INFO

Client credentials must be kept secret. However, since typical clients require limited access, an admin client is available for user management.

Standard user creation is usually possible with a normal client. We will define the exact process with you during the integration phase.

Correlation ID

GET / HTTP/1.1
x-correlation-id: c129b93a-9b5c-11e6-a112-480fcfb9550f

The Correlation-ID is used to track requests across all systems. The Correlation-ID can be passed to the BANKSapi APIs as HTTP header X-Correlation-ID.

If it is not passed, the BANKSapi APIs generate their own ID.

In any case, the value is also returned as the HTTP response header X-Correlation-ID.

INFO

The correlation ID must be a UUID

CORS

More information about CORS on Wikipedia.

BANKS/Connect supports Cross-Origin Resource Sharing (CORS), allowing you to call our APIs directly from the browser, for example in single-page applications.

Errors

Errors cannot always be avoided, but they can be handled gracefully. External dependencies such as banks and service providers connected via BANKS/Connect may have varying availability beyond our control.

Therefore, the BANKS/Connect Customer API provides message objects containing a code, a generic error description suitable for your end customers, and a detailed message for internal error handling.

For more technical errors, we use the full range of HTTP status codes, including syntax errors, authentication failures, concurrent requests, network problems, and similar conditions.

For details about the possible message objects and the HTTP status codes, see the Errors and Messages section in the BANKS/Connect Customer API documentation.

HATEOAS

More information about HATEOAS on Wikipedia.

HATEOAS stands for "Hypermedia as the Engine of Application State." With HATEOAS, a REST interface client navigates only to URLs provided by the server that are relevant in the current context. These URLs are identified by relation names that convey semantic meaning, so clients only need to know a few fixed entry points.

These URLs are communicated to clients as relations in resource representations or in the HTTP "Location" header.

Timestamp

For example:

2016-09-03 04:27:002019-12-04 13:37:002010-01-01 22:03:54

Timestamps are always output without time zone information, using the ISO 8601 format YYYY-MM-DD hh:mm:ss. Values must be interpreted in the Europe/Berlin time zone.

JSON

{
  "aString": "Lorem ipsum dolor sit amet",
  "anInteger": 42,
  "aFloat": 42.1337,
  "aBool": true,
  "aDate": "1969-07-20",
  "aTimestamp": "2016-09-03 04:27:00",
  "anArrayOfInteger":[1,2,3],
  "anArrayOfStrings":["one", "two", "three"],
  "anObject":{
     "cat": "kitten",
     "dog": "puppy"
  }
}

The BANKS/Connect interfaces use JSON (JavaScript Object Notation) for data exchange. Attributes without values are omitted rather than returned as null. Dates and timestamps are represented as ISO 8601-formatted strings.

Consumers must ignore unknown attributes in JSON documents. This is particularly important for enumeration types, where adding new values is considered backward-compatible.

When delivering JSON, the Content-Type: application/json header must always be included. For null values, fields may be omitted or sent with a null value unless they are mandatory.

Your client

There is also a demo client, for example in our Quick Start Guide.

Your client is you or the company that has entered into a cooperation agreement with us. For definitions, see Client and User.

As a client, you have access to our first-class support and benefit from the ongoing development of BANKS/Connect. You will also see more data than just our demo bank.

If you are interested, please contact us.

OAuth2

All calls to the BANKSapi interfaces must be made with a valid OAuth2 token. For some operations, a client token (without a specific user) is sufficient.

Details on user and client management are described in the BANKSapi Auth API.

Token types

BANKSapi is working in a 2-legged OAuth2 setting. This means you will be supplied a refresh token. With this, you will have to fetch a fresh access token for almost all calls within our APIs.

The refresh token (actually a set of Basic Auth credentials) is valid for a long time and used exclusively to fetch new access tokens. It is a Basic token, you will have to authenticate with Authorization: Basic <base64EncodedCredentials>

An access token has a validity of 2hrs, after which you will need to create a new token. Depending on your design and use case, we recommend that you either keep track of the validity and fetch a new token in time, or you fetch a new access token per business transaction, in which case you can go without persistence of the token. You will have to authenticate with Authorization: Bearer <bearerToken>

Token levels

Access tokens can be on client or on user level. If nothing is explicitly documented in the corresponding use case, the call with a unique user is assumed. Bear in mind you can't do calls like e.g. add a new bank access on a client (i.e. management) level as these would be available for all users, but only on user level. But a user can't create new users, this must be done on a management level.

TIP

There are two levels of tokens in BANKSapi: Management level (e.g. to create new users) and user level (e.g. to add bank accesses for a specific user).

Token usage

When calling, the token must be transferred according to the OAuth2 standard in the header "Authorization: Bearer ...". If this header is missing or the token is invalid, the interface responds with the HTTP status code 401 (Unauthorized). If the token does not contain the necessary authorizations, the HTTP status code 403 (Forbidden) is reported.

Provider

As providers we refer to the connected banks and service providers in a very abstract way. The connection is made using a wide variety of technologies and in the end the collected data will be converted into a uniform format for you.

Relation

{
    "rel": "say_hello",
    "href": "https://banksapi.io/hello/"
}

A relation corresponds to an application or business transaction that is supported by the surrounding data object. For every application and business transaction, there is a separate documentation that describes both the call and the return or the possible alternative response scenarios in the in detail.

Each relation consists of a keyword (e.g. "get_kontoumsaetze") and a URL. A client that is interested in the transactions of a bank product calls the specified URL with the HTTP verb specified in the documentation.

REST

Recommended reading: Roy Fielding: REST APIs must be hypertext-driven

Our APIs are implemented as REST patterns (Representational State Transfer). Consequently, they are usable via the HTTP protocol and use more HTTP verbs than just GET and POST.

Furthermore, we strive to meet the requirements of the REST inventor Roy Fielding for a REST API by reflecting on the HATEOAS architectural style to do justice to this.

Service Provider

Service providers are connected financial institutions that are not a bank. In the context of BANKS/Connect they are also more generally referred to as Provider.

Information about service providers can be obtained through the BANKS/Connect Providers API.

Language

The German banking domain contains many technical terms without clear English equivalents. To avoid awkward "Denglisch", we retain established German terms in German and use English for all other concepts.

Speaking of languages, BANKS/Connect is primarily implemented in Java and other JVM languages.

Encryption

{
  "plaintext": "BANKSapi",
  "Ciphertext": "ONAXFncv"
}

To allow BANKS/Connect to access bank data, your access credentials must be available. Since this information is highly sensitive, the credentials are protected by strong asymmetric encryption. You will receive an RSA public key at the start of the integration; the private key remains securely with BANKSapi. This ensures credentials can be encrypted but not decrypted by third parties.

The procedure is described in detail in the documentation for the BANKS/Connect Customer API.

We check the quality of our TLS configuration with the tool Qualys SSL Labs.

Otherwise, of course, the transport route is encrypted using TLS (HTTPS).

Versioning

Semantic versioning even has its own semantically versioned manifest.

The interfaces follow semantic versioning (X.Y, e.g., 2.0). If only the minor version (Y) increases, a correctly implemented client will continue to work without modification, though it will not use new features. If the major version (X) changes, client updates are required since the change is not backward compatible. We will continue to support previous major versions for a reasonable period after releasing an incompatible update.