Input-Constrained DevicesID: urn:ietf:params:oauth:grant-type:device_code

Device Authorization Flow

Designed for internet-connected devices that either lack a browser or have severely restricted text input, such as Smart TVs, media encoders, IoT devices, and CLI terminals.

#oauth2#device-code#smart-tv#cli#iot#secondary-device#rfc8628

Overview

The Device Authorization Grant (RFC 8628) addresses the challenge of authenticating users on devices that cannot conveniently display a web browser or accept text input (e.g. Smart TVs, gaming consoles, streaming boxes, CLI tools).

The device requests authorization from the authorization server, which returns a device_code, a human-friendly user_code (e.g. "WDJB-MJHT"), and a verification URL.

The device displays the URL and user code on its screen (often alongside a QR code) and instructs the user to open the URL on their smartphone or computer. While the user authenticates and approves access on their secondary device, the input-constrained device polls the token endpoint at regular intervals. Once approved, the device receives its tokens.

Quick Specifications

Flow Status: standard
Recommended For: Smart TV and Limited Input DeviceCLI
Token Auth Methods: None
Primary Standard: RFC 8628

Create Client with this Grant

Sequence Diagram

Visual sequence illustrating entity interactions and protocol steps

Sequence Diagram

Interactive Diagram

sequenceDiagram
    autonumber
    actor U as User
    participant D as Device (Smart TV / CLI)
    participant B as User's Phone / Browser
    participant AS as Authorization Server

    D->>AS: POST /oauth/device/code (client_id, scope)
    AS-->>D: 200 OK (device_code, user_code="WDJB-MJHT", verification_uri, interval=5)
    D->>U: Display "Visit auth.com/activate & enter code WDJB-MJHT" (or QR code)
    loop Polling every interval (5s)
        D->>AS: POST /oauth/token (grant_type=device_code, device_code, client_id)
        AS-->>D: 400 Bad Request (error="authorization_pending")
    end
    U->>B: Open auth.com/activate on phone
    B->>AS: Enter code "WDJB-MJHT" & authenticate
    AS->>U: Show consent screen & permission details
    U->>AS: Approve Device Access
    D->>AS: POST /oauth/token (next poll interval)
    AS-->>D: 200 OK (access_token, refresh_token, token_type=Bearer)
    D->>U: Authorization Successful! Display user profile

Step-by-Step Flow Breakdown

Detailed breakdown of every message exchange, query parameter, and HTTP payload

Device Requests Authorization

Device (Smart TV / CLI)→Authorization Server

The device connects to the authorization server device authorization endpoint requesting authorization with its client_id and scopes.

Device Authorization Request

POST /oauth/device/code HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

client_id=smart_tv_app_01
&scope=openid%20profile%20media%3Aplayback

Authorization Server Issues Device Codes

Authorization Server→Device (Smart TV / CLI)

The authorization server issues a device_code for polling, a human-readable user_code, a verification_uri, and the polling interval.

Device Authorization Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEqN",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://auth.example.com/activate",
  "verification_uri_complete": "https://auth.example.com/activate?user_code=WDJB-MJHT",
  "expires_in": 900,
  "interval": 5
}

Display User Code and QR Code

Device (Smart TV / CLI)→User

The device displays the URL and user code on screen, prompting the user to visit the URL on their smartphone or laptop.

Poll Token Endpoint

Device (Smart TV / CLI)→Authorization Server

The device polls the token endpoint at the designated interval. While waiting for user approval, the server replies with error="authorization_pending".

Polling Token Endpoint

POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEqN
&client_id=smart_tv_app_01

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "authorization_pending"
}

User Authenticates on Secondary Device

User→User Phone / Browser

The user visits the activation page on their smartphone or laptop, confirms the code matches the TV screen, and logs in.

User Grants Consent

User→Authorization Server

The user approves the requested permissions for the device.

Successful Token Issuance

Authorization Server→Device (Smart TV / CLI)

On the subsequent poll after user approval, the authorization server delivers access and refresh tokens to the device.

Successful Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rTv47101lK...",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Security Considerations

Critical safeguards, threat mitigations, and implementation best practices

Strict Polling Rate Limiting

Devices must adhere strictly to the minimum polling interval specified by the authorization server. If polling too fast, the server returns "slow_down" and increases the interval.