The initial authentication against the API is done by providing username/password credentials to retrieve an authentication token.

In order to support efficient M2M communications, an authenticated user may use the API to retrieve a long-lived token (referred to in this documentation as an application token) that can be used instead of user credentials in the authentication request.

It is highly recommended to use application tokens for M2M communications instead of authentications tokens.

The authentication token is then sent in all subsequent requests to the API in the ‘Authorization’ header. The token can be stored in-memory for the duration of the user session, or in local token store.

The authentication entrypoint is is a public (unauthenticated) service which does not require (and ignores) authentication tokens.

Authentication for Users

The authentication service takes as input a user name and a password and authenticates a user with his credentials. Upon successful authentication, the service returns an authentication token and a refresh token. The authentication token will be valid for 240 minutes and the refresh token is valid for 350 minutes, but it can only be used once and loses its validity if the user logs in from somewhere else (different web client).

When the authentication token has expired the user will need to re-authenticate (either with the refresh token or with the user credentials) in order to get a new authentication token. If both tokens have expired, the user will need to perform the initial authentication again.

For details on user authentication, see Basic Auth.

Authentication for Applications

When the authentication service is used with an application token instead of user credentials, it returns an authentication token only. The authentication token will be valid for 240 minutes.

After expiration, the application will need to re-authenticate by providing the application token again. The application token is valid until it expires or is revoked by an authorized user of the organisation. The expiration time of an application token is configurable during creation.

For details on application authentication, see Application Auth.