Authentication

In order to access the API, requests must be authenticated. To achieve this, an access token with the appropriate scopes must be included in each request. To create an access token for the API access, the Device Code Flow process must be initialized The process involves generating a device_code, which is then used to obtain a token.

Generate Device Code

To initiate an authentication process with the Authorization Server, a POST request needs to be made to the https://umetrics.studio/auth/realms/core/protocol/openid-connect/auth/device endpoint. Ensure that the request incorporates a Content-Type: application/x-www-form-urlencoded header and includes client_id=device-client within the body of the request.

When issuing the request in Windows, substitute curl with curl.exe and consolidate all parameters into a single line, eliminating any backslashes \ at the end of each line. Additionally, keep in mind that you can issue token using any other HTTP client.

curl --request POST \
--url "https://umetrics.studio/auth/realms/core/protocol/openid-connect/auth/device" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=device-client"

Following the request, the Authorization Server generates a response containing several key components:

{
    "device_code": "E1oZyd3a98JFtPcWDgR50leCH1xRMAZHnWMQxE21lLE",
    "user_code": "XCMX-RRUL",
    "verification_uri": "https://umetrics.studio/auth/realms/core/device",
    "verification_uri_complete": "https://umetrics.studio/auth/realms/core/device?user_code=XCMX-RRUL",
    "expires_in": 600,
    "interval": 5
}
  • device_code and user_code for the authentication process,
  • verification_uri where the user can verify the user_code,
  • verification_uri_complete that includes the user code for a more streamlined verification process.

Additionally, the response specifies the expires_in value, denoting the duration (in seconds) for which both the device_code and user_code remain valid, along with a recommended polling interval for checking the authorization status.

To complete the authorization process based on the provided response, open a web browser and:

  • navigate directly to the verification page by using the URL provided in verification_uri_complete, which already includes the user_code,
  • or alternatively, visit the verification_uri and manually enter the user_code. This method requires an additional step but is useful if the complete URL cannot be used for any reason.

Generate Access Token using Device Code

After successfully completing the verification, the device_code plays a crucial role in fetching an access token. To generate an access token for the API access, you need to execute a POST request directed to the https://umetrics.studio/auth/realms/core/protocol/openid-connect/token endpoint. This request should contain a Content-Type: application/x-www-form-urlencoded header and include device_code (the same that was received from a previous call), client_id, and grant_type within the request body.

curl --request POST \
--url "https://umetrics.studio/auth/realms/core/protocol/openid-connect/token" \
--header "Content-Type=application/x-www-form-urlencoded" \
--data "client_id=device-client" \
--data "device_code=E1oZyd3a98JFtPcWDgR50leCH1xRMAZHnWMQxE21lLE" \
--data "grant_type=urn:ietf:params:oauth:grant-type:device_code"

or

curl --request POST \
--url "https://umetrics.studio/auth/realms/core/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=device-client&device_code=E1oZyd3a98JFtPcWDgR50leCH1xRMAZHnWMQxE21lLE&grant_type=urn:ietf:params:oauth:grant-type:device_code"

Upon successful verification, the server will issue an access token (and a refresh token) in response to the request. The device application can then use the access token to make authenticated requests to the API, gaining access to protected resources.

Example response:

{
  "access_token": "<actual-access-token>",
  "expires_in": 86375,
  "refresh_expires_in": 1775,
  "refresh_token": "<actual-refresh-token>",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "95535beb-dff0-4fd0-a91c-7bb7a1b826ae",
  "scope": ""
}

Generate Access Token using Refresh Token

When requesting a token using the device code, you also receive a refresh token in the response. This refresh token can be used to generate a new access token if the current one expires. Given the intentionally short lifespan of access tokens for enhanced security, leveraging the refresh token becomes a practical approach to maintain access to APIs. To generate a new access token for the API with a refresh token, you must execute a POST request targeting the https://umetrics.studio/auth/realms/core/protocol/openid-connect/auth/token endpoint. The request should contain the Content-Type: application/x-www-form-urlencoded header and include client_id, grant_type and refresh_token within the request body.

curl --request POST \
--url "https://umetrics.studio/auth/realms/core/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=device-client" \
--data "grant_type=refresh_token" \
--data "refresh_token=<actual-refresh-token>"

or

curl --request POST \
--url "https://umetrics.studio/auth/realms/core/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "client_id=device-client&grant_type=refresh_token&refresh_token=<actual-refresh-token>"

Example response:

{
  "access_token": "<actual-access-token>",
  "expires_in": 85745,
  "refresh_expires_in": 1800,
  "refresh_token": "<actual-refresh-token>",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "95535beb-dff0-4fd0-a91c-7bb7a1b826ae",
  "scope": ""
}