Authenticating with the Konquest API using the Device Authorization flow

Article title

Authenticating with the Konquest API using the Device Authorization flow

Summary

How to authenticate as your Konquest user from scripts, CLI tools, and server-side integrations using OAuth 2.0 Device Authorization — without a client secret — and store a refresh token for ongoing API access.

Overview

Konquest uses Auth0 for authentication. API consumers can authenticate as their existing Konquest user using the OAuth 2.0 Device Authorization Grant (Device Flow). This is the recommended approach for scripts, CLI tools, and automated integrations.

Because authentication is tied to your real Konquest user identity, all tenancy restrictions apply automatically throughout the API — you will only be able to access data belonging to tenants your account is associated with.

The legacy /api/login endpoint is being retired. All API consumers should migrate to the flow described in this article.

Connection details

Value
Auth0 domain	`https://auth.konquest.io`
Client ID	`SmwPVzMiMmHNu7HWBWEwbsIlKID7lbbk`
API audience	`https://konquest-prod-konquest-web-app-api.konquest.io/api`

Part 1: Obtain a refresh token

Complete this section once during initial setup. At the end you will have a refresh token you can store and reuse to obtain access tokens on demand, without re-authenticating each time.

Step 1 — Request a device code

Send a POST request to the device/code endpoint:

POST https://auth.konquest.io/oauth/device/code
Content-Type: application/x-www-form-urlencoded

client_id=SmwPVzMiMmHNu7HWBWEwbsIlKID7lbbk
&audience=https://konquest-prod-konquest-web-app-api.konquest.io/api
&scope=openid profile email offline_access

The offline_access scope is required to receive a refresh token. Without it you will only receive a short-lived access token.

A successful response will include:

{
  "device_code": "Ag_abc123...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://auth.konquest.io/activate",
  "verification_uri_complete": "https://auth.konquest.io/activate?user_code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

Note the device_code, verification_uri_complete, interval, and expires_in values — you will need them in the following steps.

Step 2 — Authenticate in a browser

Open verification_uri_complete in any browser. You will be directed to the Konquest passwordless login. Enter your account email address and complete authentication using the magic link or one-time code sent to your inbox.

The device code expires after expires_in seconds (default: 900). Complete this step before it expires.

Step 3 — Poll for tokens

While the browser step is in progress, poll the token endpoint using the device_code from Step 1. Poll at the interval returned in the response (default: every 5 seconds).

POST https://auth.konquest.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<device_code from step 1>
&client_id=SmwPVzMiMmHNu7HWBWEwbsIlKID7lbbk

While authentication is pending you will receive {"error": "authorization_pending"}. Continue polling. Once the browser step is complete, the response will include your tokens:

{
  "access_token": "eyJ...",
  "refresh_token": "v1.Mj...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Store the refresh_token securely — treat it like a password. It should be encrypted at rest and never exposed in logs, version control, or client-side code.

Part 2: Obtain an access token

Once you have a stored refresh token, use it to obtain a fresh access token at the start of each API session or sync run. You do not need to repeat the browser authentication step.

Step 1 — Exchange the refresh token

POST https://auth.konquest.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=SmwPVzMiMmHNu7HWBWEwbsIlKID7lbbk
&refresh_token=<your stored refresh token>

A successful response returns a new access token:

{
  "access_token": "eyJ...",
  "refresh_token": "v1.Nk...",
  "token_type": "Bearer",
  "expires_in": 86400
}

The response may include a new refresh_token. If it does, replace your stored refresh token with the new value. Using a superseded refresh token may result in an error requiring you to repeat Part 1.

Step 2 — Call the API

Include the access token as a Bearer token in the Authorization header of all Konquest API requests:

GET https://konquest-prod-konquest-web-app-api.konquest.io/api/some-endpoint
Authorization: Bearer <access token>

Access tokens are short-lived (typically 24 hours). Request a fresh one via the refresh token flow at the start of each session rather than storing the access token long-term.

A note on tenancy

Tenancy context is populated when you first authenticate via the browser step in Part 1. Your token will reflect the tenants associated with your Konquest user account at that time.

If your tenancy configuration changes after initial setup — for example, you are added to a new tenant — your existing refresh token chain may carry stale tenancy claims until you re-authenticate. If you notice missing data following a tenancy change, repeat Part 1 to obtain fresh credentials.

Troubleshooting

Error	Likely cause and resolution
unauthorized_client	The client ID is incorrect, or the Device Code grant is not enabled. Contact Konquest support.
authorization_pending	The user has not yet completed browser authentication. Continue polling.
expired_token	The device code has expired (default: 900 seconds). Restart from Part 1, Step 1.
invalid_grant	The refresh token is invalid or has been revoked. Restart from Part 1.
access_denied	The user denied the authorisation request in the browser.