Client Authorization

Access Tokens

To access the financial data of a user, the client has to authenticate itself with a token. This token is called an access token and contains information on the client, the user and the resources he is authorized to use. This token has to be passed with the HTTP Authorization-header in each request to the API.

Authorization: Bearer <access-token>

The access token is formatted as a JSON Web Token according to RFC7519 and expires after a short time (e.g. 1 hour) so that it has to be frequently recreated.

To get an access token you can

• exchange an authorization code that you obtained after a successful OAuth login flow (authorization_code grant). An authorization code can only be used once and has a short lifetime e.g. 5 minutes.
• login with the user's password (password grant). The password does not expire, but three consecutive wrong attempts will lock the user.
• exchange a refresh token, which is returned for either of the aforementioned options (refresh_token grant)

Authentication errors

In case of an authentication error, an HTTP code 401 response is returned containing further
details on the kind of error in the WWW-Authenticate header.

Refresh Tokens

A refresh token allows it to request additional access tokens (e.g. after the access token has expired). Refresh tokens are only valid to a maximum of 90 days.

When issuing a refresh request, the response may contain a new refresh token so that your application has to discard the old token and replace it with the new refresh token.

📘

The actual length in bytes of all tokens (access and refresh tokens as well as authorization
codes) can vary. Therefore, it is highly advised to not limit the size of the database field
in your storage backend. If you have to specify a size for the corresponding database field
a choice of at least 2048 bytes is highly recommended.

Scope

Each client has a set of permissions associated with him, that defines the access scope on the API.

Example

The string "accounts=rw submit_payments" is URL-encoded and passed as the URL parameter scope.