User and device tokens

SAFEQ Cloud server allows a fine-grained control over the public API access on user level or device (client) level. For that purpose there is a concept of user token and device token:

• User token: this is a token acquired after calling a login function of the public API. It should be provided to all other functions
• Device token: this is a token acquired after calling the SAFEQ Cloud OAuth service and establishing a trust relation between the client and the server. Device token should be provided when calling a login function of the public API.

Access tokens have a short expiration time (typically one hour). They can be renewed using a refresh token (which is returned as a part of TokenInfo structure) to maintain a login state longer than 1 hour. Refresh tokens are usually valid for 3 months, after that the user must re-authenticate (or device re-registered).

Token validity times can be configured in the account settings in SAFEQ Cloud server administration UI.

API key has two parameters which control the security of the public API endpoints:

• Allow unauthenticated requests: allows to call API functions without the user token or to authenticate with insecure credentials (card ID, short ID, user name only, email address). If this option is disabled (default) the client is required to call the /login endpoint first and provide the returned access token to all other API requests as a Authorization: Bearer <user_token> HTTP header. Failure to provide a token will result in error 403 for all requests.

• Allow untrusted endpoints: if enabled this option allows to authenticate from any client without obtaining a trusted device token first. If disabled (default) the client is required to be in a trusted relation with SAFEQ Cloud server and provide a device token when calling the /login endpoint, in a form of Authorization: Bearer <device_token> header.