Skip to main content

Authentication

How does our authentication work?​

The access to our API's is secured via OAuth2. In order to access an API you will have to provide an accessToken via the Authorization header for every request.

Once you have obtained credentials for an API-Client you will receive an access and refresh token pair via the /access endpoint. The accessToken has to be provided for for every API request via the Authorization header.

HTTP header
Authorization: Bearer <accessToken>

The /access endpoint will also return the expiration time of the access and refresh token.

{
    "accessToken": "eyJraWQiOiIyMDE4MDYxOS1kZXYiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdW....eYUV_VGR-pyls1BpGapLzsy3LyGHJMbUY",
    "refreshToken": "1001..HWZdylvuj_1....f76S_7RK_IhNr",
    "accessExpiration": 1732402800,
    "refreshExpiration": 1732413600
}

Token validity​

How long is an access token valid?​

Access tokens have an validity of 30 minutes. The exact date/time the token will expire will be returned via the accessExpiration field in the /access and /refresh calls.

How long is an refresh token valid?​

Refresh tokens have an validity of 3 hours. The exact date/time the token will expire will be returned via the refreshExpiration field in the /access and /refresh calls.

How to handle an expired access token?​

Access tokens will expire 30 minutes after their creation. To get a new valid access token after it expired you have to use the /refresh endpoint.

What are scopes?​

Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. In context of our API's the only existing scope is api. You have to provide it for the /api/auth/access endpoint to obtain the access and refresh token.