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. | |
| refresh_token | Renew an active session using a refresh token. | |
| third_party_token_exchange | Authenticate using a token from a third-party authentication service. | |
| stb_pwless | Authenticate a previously provisioned device using a public-key certificate. |
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:
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 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 their session (typically when logging out), the session should be revoked, rendering the refresh token unusable.