Device Authorization Flow

The Device Authorization Flow is the OAuth flow for devices that cannot run a browser or accept typed credentials — CLI tools, smart TVs, game consoles, IoT devices, and kiosks. The device shows a short user code and a verification URL; the user opens that URL on a second device (phone or laptop), logs in, and types the code. The device polls the token endpoint until the user finishes, then receives tokens.

The flow is defined by RFC 8628 — OAuth 2.0 Device Authorization Grant: the flow used by CLIs, smart TVs, and other input-constrained devices. The device shows a short user_code; the user types it on a second device to authorize.

---

How It Works

1. Device requests authorization — calls the device authorization endpoint.
2. User code displayed — the device shows a code and a URL to the user.
3. User opens URL on another device — typically phone or laptop.
4. User enters the code and authenticates — standard login flow on the second device.
5. Device polls for tokens — periodically checks if the user has completed authentication.
6. Tokens issued — once the user authorizes, the device receives access and refresh tokens.

---

Endpoints

All device flow endpoints are organization-specific:

Endpoint	URL	Purpose
Device Authorization	/orgs/{orgId}/api/v1/oauth/device_authorization	Request device + user codes
Device Verification	/orgs/{orgId}/device	User-facing page to enter the code
Token	/orgs/{orgId}/api/v1/oauth/token	Poll for tokens (grant_type=device_code)

---

Step-by-Step Guide

1. Request Device Authorization

The device calls the authorization endpoint:

curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/oauth/device_authorization \
  -d client_id=YOUR_CLIENT_ID \
  -d scope="openid profile email"

Response:

{
  "device_code": "GmRh...device_code",
  "user_code": "ABCD-1234",
  "verification_uri": "https://your-domain.com/orgs/{orgId}/device",
  "verification_uri_complete": "https://your-domain.com/orgs/{orgId}/device?user_code=ABCD-1234",
  "expires_in": 1800,
  "interval": 5
}

2. Display the Code to the User

The device displays:

To sign in, visit: https://your-domain.com/orgs/acme-corp/device
Enter code: ABCD-1234

Or display a QR code pointing to verification_uri_complete for a smoother mobile experience.

3. User Authenticates on Their Device

The user:

1. Opens the verification URL.
2. Enters the user code (if not in the URL).
3. Logs in with their credentials (or social login).
4. Approves the device.

4. Device Polls for Tokens

The device polls the token endpoint at the specified interval:

curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=GmRh...device_code \
  -d client_id=YOUR_CLIENT_ID

While waiting:

{
  "error": "authorization_pending",
  "error_description": "The user has not yet completed authorization"
}

After user authorizes:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def...",
  "id_token": "eyJ..."
}

---

Use Cases

Device	Example
CLI Tools	lumo login command that displays a code
Smart TVs	Streaming apps that display a code on screen
IoT Devices	Connected devices without a full browser
Kiosks	Public terminals with limited input capabilities
Game Consoles	Authenticate with a code shown on the TV

---

Configuration

Create a Device Flow Application

1. Go to /orgs/{orgId}/portal/applications.
2. Create a new application with grant type: Device Authorization.
3. Set the client as a public client (no client secret for devices).
4. Configure allowed scopes.

Device Code Settings

Setting	Description	Default
Code Expiration	How long the user code is valid	30 minutes
Polling Interval	Minimum seconds between token polls	5 seconds
User Code Format	Format of the code shown to users	XXXX-XXXX

---

Related Guides

• Authentication Overview — all authentication methods
• Device Authorization Grant (API reference) — endpoint details and error codes
• OAuth 2.0 & OIDC — token management and OAuth flows