How to Add Device Authorization Flow to Your App With Kinde

Most auth tutorials assume there is a browser. Here is what to do when there is not.

In this article, you will learn:

• What the device authorization flow is and why it exists
• When to use it over other OAuth flows
• How to set up a Device and IoT application in Kinde
• How to implement the full flow end to end in Node.js
• How to poll for tokens correctly and handle every error state
• How to validate the access token on your API

Let's dive in!

The Problem With Browser-Based Auth

Every standard OAuth flow assumes the same thing: the user is sitting in front of a browser, they can get redirected to a login page, and they can type their credentials into a form.

That assumption breaks the moment you step outside the browser. A CLI tool cannot open a redirect. A smart TV has no way to display a full login form usably. A Raspberry Pi running a background process has no UI at all. An AI agent executing tasks on behalf of a user has no session to attach to.

For all of these cases, the OAuth 2.0 Device Authorization Grant (defined in RFC 8628) is the right answer. Instead of redirecting the device to a login page, the device asks the authorization server for a short user code and a URL, displays them to the user, and then polls for a token while the user completes login on a separate device — their phone or laptop — that actually has a browser.

The device never handles credentials. The user authenticates on a device they trust. The token lands on the original device once the user approves.

This flow is why logging into Netflix on a smart TV works the way it does. It is also how tools like the GitHub CLI, the Vercel CLI, and the AWS CLI authenticate their users without opening a browser window programmatically.

When to Use the Device Flow

The device flow is not a general-purpose replacement for the authorization code flow. Use it specifically when:

• Your application runs in a terminal or CLI and cannot reliably open a browser
• Your application runs on a device with limited or no input capabilities (smart TVs, set-top boxes, IoT hardware)
• You are building an AI agent or automation that needs to authenticate on behalf of a human user but runs in a headless environment
• You are building a desktop background process or daemon that needs user-level tokens without a UI

For standard web apps, mobile apps, or SPAs where a browser is available, stick with the authorization code flow with PKCE. The device flow adds polling complexity that you do not need when a redirect is possible.

Prerequisites

Before writing any code, make sure you have:

• A Kinde account — free to sign up, no credit card required
• Node.js 18 or later installed locally
• A basic understanding of OAuth 2.0 token concepts

Step #1: Create a Device and IoT Application in Kinde

The device authorization flow requires a specific application type in Kinde. You cannot use an existing web or SPA application for this — the application type determines which OAuth grants are allowed.

In your Kinde dashboard, navigate to Applications and select Add application. Give it a descriptive name like My CLI Tool or Device App. Under application type, select Device and IoT. Select Save.

Once created, open the application details and note the Client ID. You will need this in every request. Device and IoT applications in Kinde do not have a client secret — the flow is designed for public clients that cannot securely store secrets.

Next, configure the authentication method for this application. Navigate to Settings > Authentication, select Configure on the Passwordless > Email + code card, and under Applications select the Device and IoT application you just created. Select Save.

This tells Kinde to use email OTP as the authentication method when a user goes to the verification URL from this application. Users will receive a one-time code by email rather than needing a password.

Step #2: Understand the Full Flow

Before writing code, it helps to see the complete sequence clearly.

Phase 1 — Device requests authorization:
Your device (the CLI, the TV, the background process) sends a POST request to Kinde's device authorization endpoint. Kinde responds with a device_code, a user_code, a verification_uri, and a verification_uri_complete.

Phase 2 — User authenticates:
Your device displays the user_code and the verification_uri to the user. The user visits the URL on their phone or laptop, enters the code, and authenticates through Kinde's normal login flow.

Phase 3 — Device polls for token:
While the user is authenticating, your device polls Kinde's token endpoint every few seconds using the device_code. Kinde returns authorization_pending until the user completes login, at which point it returns the access token.

Phase 4 — Device uses the token:
Your device now has a standard OAuth 2.0 Bearer token. It uses this to call your API.

The device_code is what your device uses internally. The user_code is what the human types. The verification_uri_complete is the full URL with the code pre-filled — useful for generating a QR code so the user does not have to type anything.

Step #3: Request the Device Code

Here is the first API call your device makes:

// src/auth.ts
import https from "https";
import { URLSearchParams } from "url";

const KINDE_DOMAIN = "YOUR_SUBDOMAIN.kinde.com";
const CLIENT_ID = "YOUR_CLIENT_ID";

interface DeviceCodeResponse {
  device_code: string;
  user_code: string;
  verification_uri: string;
  verification_uri_complete: string;
  expires_in: number;   // how long the codes are valid (seconds)
  interval: number;     // minimum polling interval (seconds)
}

async function requestDeviceCode(): Promise<DeviceCodeResponse> {
  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    scope: "openid profile email offline",
  });

  const response = await fetch(
    `https://${KINDE_DOMAIN}/oauth2/device/auth`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: params.toString(),
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Device code request failed: ${error}`);
  }

  return response.json() as Promise<DeviceCodeResponse>;
}

The scope values follow the standard OIDC conventions: openid requests an ID token, profile and email include the user's name and email in the token claims, and offline requests a refresh token so you can obtain new access tokens without requiring the user to re-authenticate.

The response from Kinde looks like this:

{
  "device_code": "kinde_dc_...",
  "user_code": "CSLDFDUU",
  "verification_uri": "https://your-subdomain.kinde.com/device",
  "verification_uri_complete": "https://your-subdomain.kinde.com/device?user_code=CSLDFDUU",
  "expires_in": 600,
  "interval": 5,
  "qr_code": "data:image/png;base64,..."
}

The user_code in Kinde is formatted as 8 uppercase characters for easy manual entry. The expires_in is 600 seconds (10 minutes) — that is how long the user has to complete the login before the codes expire. The qr_code field is a base64-encoded PNG image that you can render directly on screen, which means users with a camera can scan it instead of typing the URL and code manually.

Step #4: Display the Code to the User

Once you have the device code response, show the user what they need to do. For a CLI tool this is straightforward:

// src/cli.ts
async function startAuth() {
  console.log("\nRequesting authorization...\n");

  const deviceCodeData = await requestDeviceCode();

  console.log("To authenticate, visit:");
  console.log(`\n  ${deviceCodeData.verification_uri}\n`);
  console.log(`Enter this code: ${deviceCodeData.user_code}`);
  console.log(`\nOr open this URL directly (code pre-filled):`);
  console.log(`\n  ${deviceCodeData.verification_uri_complete}\n`);
  console.log(`Or scan the QR code if your device can display images.\n`);
  console.log(
    `Waiting for you to authenticate... (expires in ${Math.floor(deviceCodeData.expires_in / 60)} minutes)\n`
  );

  // Begin polling
  const token = await pollForToken(deviceCodeData);
  return token;
}

For a smart TV or embedded device, you would render the user_code prominently on screen alongside the verification_uri, or generate a QR code from verification_uri_complete so the user can scan it with their phone without typing anything.

Step #5: Poll for the Token

This is where most implementations go wrong. Polling is not just "keep hitting the token endpoint until it works." There are specific error states you must handle correctly.

// src/auth.ts

interface TokenResponse {
  access_token: string;
  id_token?: string;
  refresh_token?: string;
  expires_in: number;
  token_type: string;
}

type PollError =
  | "authorization_pending"  // user has not finished yet — keep polling
  | "slow_down"              // polling too fast — increase interval by 5 seconds
  | "access_denied"          // user explicitly denied — stop polling
  | "expired_token";         // codes have expired — restart the flow

async function pollForToken(
  deviceCodeData: DeviceCodeResponse
): Promise<TokenResponse> {
  let interval = deviceCodeData.interval; // start at 5 seconds
  const expiresAt = Date.now() + deviceCodeData.expires_in * 1000;

  while (Date.now() < expiresAt) {
    // Wait the current interval before polling
    await sleep(interval * 1000);

    const params = new URLSearchParams({
      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
      client_id: CLIENT_ID,
      device_code: deviceCodeData.device_code,
    });

    const response = await fetch(`https://${KINDE_DOMAIN}/oauth2/token`, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: params.toString(),
    });

    if (response.ok) {
      // User authenticated — we have a token
      return response.json() as Promise<TokenResponse>;
    }

    const error = await response.json() as { error: PollError; error_description?: string };

    switch (error.error) {
      case "authorization_pending":
        // Normal state — user has not finished yet, keep waiting
        continue;

      case "slow_down":
        // We are polling too fast — increase interval by 5 seconds
        interval += 5;
        console.log(`Slowing down polling to every ${interval} seconds...`);
        continue;

      case "access_denied":
        // User explicitly denied the authorization
        throw new Error("Authorization was denied by the user.");

      case "expired_token":
        // The device code has expired — need to restart
        throw new Error(
          "The authorization code expired. Please run the command again."
        );

      default:
        throw new Error(
          `Unexpected error during polling: ${error.error} — ${error.error_description}`
        );
    }
  }

  throw new Error(
    "Authentication timed out. Please run the command again."
  );
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

A few things to pay attention to here:

Always wait before the first poll. The interval from the response is the minimum time between requests. Make the first poll after waiting that interval, not immediately after displaying the code to the user.

Handle slow_down correctly. When Kinde returns slow_down, you must increase your polling interval by 5 seconds for that request and all subsequent requests. Ignoring this and continuing at the original interval will result in your requests being rejected.

Respect expires_in. Stop polling when the device code expires. Do not continue indefinitely. If the code expires, the user needs to restart the process.

Distinguish authorization_pending from errors. authorization_pending is not an error — it just means the user has not finished yet. Everything else in the error response is a real problem that requires action.

Step #6: Store and Use the Token

Once polling succeeds, you have a standard OAuth 2.0 Bearer token. Store it securely and use it to authenticate API requests.

// src/token-store.ts
import fs from "fs";
import os from "os";
import path from "path";

const TOKEN_PATH = path.join(os.homedir(), ".myapp", "token.json");

interface StoredToken {
  access_token: string;
  refresh_token?: string;
  expires_at: number; // Unix timestamp in ms
}

export function saveToken(tokenResponse: TokenResponse): void {
  const dir = path.dirname(TOKEN_PATH);
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }

  const stored: StoredToken = {
    access_token: tokenResponse.access_token,
    refresh_token: tokenResponse.refresh_token,
    expires_at: Date.now() + tokenResponse.expires_in * 1000,
  };

  fs.writeFileSync(TOKEN_PATH, JSON.stringify(stored, null, 2), {
    mode: 0o600, // owner read/write only
  });
}

export function loadToken(): StoredToken | null {
  if (!fs.existsSync(TOKEN_PATH)) return null;

  try {
    return JSON.parse(fs.readFileSync(TOKEN_PATH, "utf-8")) as StoredToken;
  } catch {
    return null;
  }
}

export function isTokenExpired(token: StoredToken): boolean {
  // Add a 60-second buffer to account for clock skew
  return Date.now() >= token.expires_at - 60_000;
}

The file permissions on the token file (0o600) are important. This ensures only the current user can read the stored token, which matters when your tool runs on a shared machine.

To call your API with the token:

// src/api.ts
import { loadToken, isTokenExpired } from "./token-store";

async function callApi(endpoint: string): Promise<unknown> {
  const stored = loadToken();

  if (!stored || isTokenExpired(stored)) {
    throw new Error(
      "Not authenticated or session expired. Run `myapp login` to authenticate."
    );
  }

  const response = await fetch(`https://api.yourapp.com${endpoint}`, {
    headers: {
      Authorization: `Bearer ${stored.access_token}`,
      "Content-Type": "application/json",
    },
  });

  if (response.status === 401) {
    throw new Error(
      "Authentication failed. Run `myapp login` to re-authenticate."
    );
  }

  return response.json();
}

Step #7: Validate the Token on Your API

The device receives a standard JWT access token issued by Kinde. Your API validates it the same way it validates tokens from any other Kinde flow — by checking the signature against Kinde's public JWKS endpoint.

// api-server/middleware/auth.ts
import jwt from "jsonwebtoken";
import jwksClient from "jwks-rsa";

const KINDE_DOMAIN = "YOUR_SUBDOMAIN.kinde.com";

const client = jwksClient({
  jwksUri: `https://${KINDE_DOMAIN}/.well-known/jwks.json`,
  cache: true,
  cacheMaxAge: 600_000, // cache keys for 10 minutes
});

function getSigningKey(
  header: jwt.JwtHeader,
  callback: jwt.SigningKeyCallback
) {
  client.getSigningKey(header.kid!, (err, key) => {
    if (err) return callback(err);
    callback(null, key!.getPublicKey());
  });
}

export function verifyToken(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const authHeader = req.headers["authorization"];
  const token = authHeader?.split(" ")[1];

  if (!token) {
    return res.status(401).json({ error: "No token provided" });
  }

  jwt.verify(
    token,
    getSigningKey,
    {
      algorithms: ["RS256"],
      issuer: `https://${KINDE_DOMAIN}`,
    },
    (err, decoded) => {
      if (err) {
        return res.status(403).json({ error: "Invalid token" });
      }

      // Attach the decoded claims to the request for use in route handlers
      (req as any).user = decoded;
      next();
    }
  );
}

The token issued via device flow contains the same claims as any other Kinde access token: sub (the user's Kinde ID), email, name, org_code if the user is in an organization, and any roles and permissions you have configured. Your API does not need to know or care that the token came from a device flow — the validation is identical.

Putting It All Together

Here is a complete CLI entry point that wires up everything above:

// src/index.ts
import { startAuth } from "./auth";
import { saveToken, loadToken, isTokenExpired } from "./token-store";
import { callApi } from "./api";

async function main() {
  const command = process.argv[2];

  if (command === "login") {
    console.log("Starting authentication...");
    const token = await startAuth();
    saveToken(token);
    console.log("\nAuthenticated successfully. You can now use the CLI.\n");
    return;
  }

  if (command === "whoami") {
    const stored = loadToken();

    if (!stored || isTokenExpired(stored)) {
      console.error("Not authenticated. Run `myapp login` first.");
      process.exit(1);
    }

    const user = await callApi("/me");
    console.log(user);
    return;
  }

  if (command === "logout") {
    const tokenPath = path.join(os.homedir(), ".myapp", "token.json");
    if (fs.existsSync(tokenPath)) {
      fs.unlinkSync(tokenPath);
      console.log("Logged out successfully.");
    } else {
      console.log("No active session found.");
    }
    return;
  }

  console.log("Usage: myapp <login|whoami|logout>");
}

main().catch((err) => {
  console.error(err.message);
  process.exit(1);
});

Running myapp login kicks off the device flow, shows the user a code and URL, polls until they authenticate, and saves the token locally. Every subsequent command loads the token silently from disk and uses it without interrupting the user.

Common Mistakes to Avoid

Polling immediately after displaying the code. Always wait the interval before the first poll. Hitting the token endpoint immediately wastes a request and may trigger rate limiting.

Not handling slow_down. If you receive a slow_down error and keep polling at the same rate, your requests will continue to fail. Increase the interval by 5 seconds and keep increasing it if you receive the error again.

Restarting the whole flow when authorization_pending is returned. authorization_pending means keep waiting, not start over. Only restart the flow if you receive expired_token or if the expires_in window has elapsed.

Storing the token with world-readable permissions. A token file stored at ~/.myapp/token.json with permissions 0o644 can be read by other users on the same machine. Always write token files with 0o600.

Not handling token expiry. Access tokens from Kinde expire after one hour by default. Check the expiry before every API call and prompt the user to re-authenticate if the token is expired. If you requested a refresh token (by including offline in your scopes), you can use it to get a new access token silently.

What This Enables

With device authorization flow in place, your CLI, IoT device, or headless process can authenticate real users through Kinde's full auth stack — including MFA, SSO, and org-scoped tokens — without any of that logic living in your device code. The user authenticates on a device they trust, your device gets a token, and your API validates it the same way it validates every other token.

For AI agents and automation workflows that need to act on behalf of authenticated users, this flow is the right foundation. The agent does not handle credentials. The user authorizes it explicitly. The token carries the same org and permission claims as any browser-based session.

Kinde handles the auth infrastructure — the user code generation, the verification page, the token issuance, the JWKS endpoint — so the only code you write is the polling loop and the token storage. Sign up for free and have your first device flow working in under an hour.