Oauth 2.0 based authentication
- Thomas Langenskiold
- Antti Peltosaari (Unlicensed)
- Phi Le
The service provides an authentication mechanism based on the Oauth 2.0 protocol.
The authentication mechanism makes use of Oauth2.0 JWT access tokens that you must obtain by authenticating with the service through the Authentication API.
Obtaining an access token
Use the access tokens endpoint to obtain the access token.
There are several supported grant types, allowing clients different ways of authenticating.
| Grant type | Description | Guidelines |
|---|---|---|
password | Authenticate using a username and password. | |
| device_code | Authenticate a device using a secondary device. | Device Authorization Grant |
| refresh_token | Renew an active session using a refresh token. | |
| third_party_token_exchange | Authenticate using a token from a third-party authentication service. | Third-party token exchange grant |
| stb_pwless | Authenticate a previously provisioned device using a public-key certificate. | STB passwordless auth grant |
Using the access token
Once you have obtained the access token, you can use the service by providing the access token in the Authorization header in every request to an API that requires authorization:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJFbmFibGVTVEIiLCJpYXQiOjE1MzE4MzQyNDEsImV4cCI6MTU2MzM3MDI0MSwiYXVkIjoid3d3LmFtaW5vY29tLmNvbSIsInN1YiI6ImFuZHkuYmVha0BhbWlub2NvbS5jb20ifQ.jtTwO3YEyXmEf5XjjxUK8V_MPRvxdi7DN1eEBUyjfkE
Renew the session
The access token has a limited lifetime, once it expires it can no longer be used. You must then obtain a new access token from the access tokens endpoint using the refresh_token grant type.
Refresh tokens are obtained from the access tokens endpoint together with the access token. Refresh tokens are not used in the authorization header, they are only used to renew an active session using the refresh_token grant type with the access tokens endpoint.
Refresh tokens also have a limited lifetime, but they are much longer lived than access tokens. When you renew a session, you are given a new set of access token and refresh token. Once used, a refresh token is no longer usable.
Revoking a session
When a user wishes to end a session (typically when logging out), the session should be revoked, rendering the refresh token unusable.
Revoke a session using the User sessions API. A session can be revoked by providing either the refresh token or the session ID, or by revoking all of the user's active sessions at once.
A list of active sessions can be obtained through the get user sessions endpoint.
Access tokens cannot be revoked, but they will expire after a while. When a session is ended, any remaining unexpired access tokens should simply be discarded.
The examples for performing the call for revoking the refresh tokens can be found in the Postman collection below.