OAuth 2.0 Device Code Flow for Input-Constrained Devices

Device Authorization Grant (RFC 8628)

The Device Code flow enables OAuth 2.0 authentication on devices that lack a convenient text-input mechanism — smart TVs, game consoles, printers, CLI tools, and IoT devices. Instead of entering credentials on the device itself, the user completes authentication on a separate device with a full browser.

How It Works

1. Device Authorization Request: The device sends a POST to /device/code with its client_id and desired scope.

2. Device Code Response: The server returns a device_code, a short human-readable user_code, a verification_uri, and a polling interval.

3. User Instruction: The device displays the user_code and verification_uri to the user (e.g., "Go to https://example.com/device and enter code: WDJB-MJHT").

4. User Authorization: The user visits the URL on their phone or laptop, enters the code, logs in, and grants consent.

5. Polling: Meanwhile, the device polls the /token endpoint at the specified interval using grant_type=urn:ietf:params:oauth:grant-type:device_code.

6. Access Token: Once the user completes authorization, the next poll returns an access token. Before that, the server responds with authorization_pending or slow_down errors.

Polling Responses

Error	Meaning
authorization_pending	User hasn't completed authorization yet — keep polling
slow_down	Polling too fast — increase interval by 5 seconds
expired_token	Device code has expired — start over
access_denied	User denied the request

Security Considerations

• Use high-entropy user codes to prevent brute-force guessing
• Implement rate limiting on the polling endpoint
• Set reasonable expiration for device codes (10-15 minutes)
• Display the complete verification URI clearly