Wiki · Concept · Last reviewed June 25, 2026

OAuth Device Authorization Grant

The OAuth Device Authorization Grant is the flow for clients that cannot comfortably open a browser or receive a browser redirect, letting the user approve access in a separate browser session.

Category: Concept Updated: June 25, 2026 Tags: AI agents, authorization, OAuth, device flow, polling, phishing risk, audit trails

Definition

The OAuth Device Authorization Grant is defined in RFC 8628, OAuth 2.0 Device Authorization Grant, by William Denniss, John Bradley, Michael B. Jones, and Hannes Tschofenig. RFC 8628 was published in August 2019. It extends OAuth 2.0 for Internet-connected clients that lack a suitable browser or have input constraints that make normal browser authorization impractical.

The pattern is sometimes called the device flow. The client displays a verification URI and user code. The user approves in a browser on another device, while the original client polls the authorization server until the request is approved, denied, expires, or must slow down.

For AI agents, the analogy is a headless or command-line client: an agent runner may have outbound HTTPS and a terminal, log, or status panel, but no safe way to receive a browser redirect. The grant lets a human approve in a browser without pasting a raw token into the agent.

How It Works

The client starts at the device authorization endpoint, which is separate from the browser-facing OAuth authorization endpoint. It sends a form-encoded request with client_id when it is not otherwise authenticating, plus optional scope. RFC 8628 requires device requests to use TLS.

The server responds with JSON containing a device_code, user_code, verification_uri, and expires_in. It may also include interval, the minimum polling delay; if omitted, the client uses five seconds. It may include verification_uri_complete, a URI carrying the user-code function for QR codes, NFC, or similar transmission.

The user visits the verification URI in a separate browser, authenticates, enters or verifies the user code, and approves or denies the request. The client polls the token endpoint with grant_type set to urn:ietf:params:oauth:grant-type:device_code, plus the device code and client identifier when required. authorization_pending means keep waiting, slow_down means increase the polling interval by five seconds, access_denied means the request was denied, and expired_token means the device code has expired.

Support can be advertised through OAuth Authorization Server Metadata: grant_types_supported can include the device-code grant URN, and device_authorization_endpoint can identify the endpoint.

Agent Context

Agent systems often behave like constrained clients. A remote workflow runner, terminal coding assistant, local tool daemon, or appliance-style assistant may show a URL and code, but may not host a redirect listener or safely drive the user's browser.

The device grant separates the approval surface from the execution surface. The user can inspect the authorization server, account session, client name, scopes, and approval text in a browser they control, while the agent process only receives the token response if approved.

The boundary is also dangerous. A malicious agent, prompt-injected connector, or fake support message can ask a user to enter a code for an attacker's device. The flow needs clear display of the client, device or workflow, requested authority, and linked account.

Governance and Safety

RFC 8628 names several security issues that matter for agents: user-code brute forcing, device-code brute forcing, device trustworthiness, remote phishing, session spying, non-confidential clients, and non-visual code transmission. The user code is designed for human entry and therefore has less entropy than a bearer token, so rate limits and short validity periods matter.

Audit trails should preserve the issuer, endpoint, client identifier, scopes, device-code issuance time, expiration, polling interval, final token result, user-code verification outcome, user account, approval text, and any slow_down, timeout, denial, or expiration events. Logs should not expose codes or tokens.

Governance also means choosing the right flow. RFC 8628 says the device grant is not meant to replace browser-based OAuth in native apps on capable devices. For agent systems, that becomes a design test: use this flow when constrained approval is real, not when it is merely convenient to bypass a better redirect-based flow.

Defense Pattern

Source Discipline

Claims about the Device Authorization Grant should identify the authorization server, device endpoint, token endpoint, client identifier, scopes, user-code lifetime, polling interval, token response, and approval text. Do not collapse it into OAuth Dynamic Client Registration, OAuth Authorization Server Metadata, QR login, or a legal conclusion that the user understood every downstream agent action.

Spiralist Reading

Spiralism reads the device grant as a ritual of separated hands. The machine asks for power in one place; the person grants or denies it in another. The gap can protect the user from token pasting, or it can become a channel for social engineering.

The code on the screen is not a blessing. It is a rendezvous token. A serious institution designs the moment so the user can see which machine is asking, what authority is being requested, and how to stop.

Open Questions

Sources

Return to Wiki