Device Authorization Grant
The default for headless and command-line agents. Read alongside RFC 10027.
Flows / Human present
Device authorization grant
For agents with no browser of their own: show a code, let the person approve on another device, and poll.
A coding agent in a remote container, a CLI over SSH, a job in a sandbox: none of them can open a browser window or receive a redirect. The device authorization grant splits the flow across two devices. The agent displays a short code and a URL; the user opens that URL on a phone or laptop, signs in, and types the code. Meanwhile the agent polls the token endpoint until the answer arrives.
It is simple and widely deployed, which is why it is the first thing people reach for with headless agents. It is also the flow most abused for phishing, because the person approving has no technical proof that the code on their screen came from the session they think it did.
Step by step
10 steps between 4 parties. Each step shows the message and who holds which credential afterward. Use ←→ or select any arrow.
Sequence diagram4 participants, 10 steps
- Direct call
- Via the user’s browser or device
- Response
- Out of band
Drag to see every party and step. Tap a step to jump to its explanation.
The agent asks to start a device flow
No user is involved yet. The agent identifies itself and says what it wants.
POST /device_authorization HTTP/1.1 Host: auth.example Content-Type: application/x-www-form-urlencoded client_id=cli-agent &scope=repo.readThe server returns two codes
The
device_codeis a long secret the agent keeps and uses to poll. Theuser_codeis short enough to type.verification_uri_completeembeds the user code so it can be rendered as a QR code.{ "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS", "user_code": "WDJB-MJHT", "verification_uri": "https://auth.example/device", "verification_uri_complete": "https://auth.example/device?user_code=WDJB-MJHT", "expires_in": 600, "interval": 5 }Who holds what after this step
- Headless agent
- newdevice_code
Parties not listed hold none of this flow’s credentials at this point.
The agent shows the code
In a terminal, a chat message, or a QR code. This hop is the weak point: nothing technical ties the code the user sees to the agent they intend to authorize. Whatever channel carries it is the channel an attacker will imitate.
To sign in, open https://auth.example/device and enter the code WDJB-MJHTWho holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
The user signs in on a second device
The user authenticates in a real browser, with whatever factors the server requires, then enters the code. The server looks up the pending request and shows what is being asked for.
Who holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
The agent polls
While the user is busy, the agent asks the token endpoint whether a decision has been made, no more often than
intervalseconds. Theresourceparameter names the API the token is for. RFC 8707 defines it on token requests for every grant type; RFC 8628 gives the device authorization request onlyclient_idandscope.POST /token HTTP/1.1 Host: auth.example Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:device_code &device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS &client_id=cli-agent &resource=https://git.example/apiWho holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
Not yet
The expected answer until the user finishes. Other answers:
slow_down(back off),access_denied(the user said no),expired_token(start again).{ "error": "authorization_pending" }Who holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
The user approves
A good approval screen names the client, says where the request came from, and lists the scopes in plain language. It is the user’s only chance to notice that they did not start this.
Who holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
The agent polls again
Same request as before.
Who holds what after this step
- Headless agent
- device_code
Parties not listed hold none of this flow’s credentials at this point.
The server issues tokens
From here on the agent is in the same position as after an authorization code flow: a short-lived access token and usually a refresh token.
Who holds what after this step
- Headless agent
- newaccess tokennewrefresh tokenused up
device_code
Parties not listed hold none of this flow’s credentials at this point.
The agent calls the API as the user
The API sees an ordinary access token. It cannot tell that the approval happened on a different device from the one making the call.
Who holds what after this step
- Headless agent
- access tokenrefresh token
Parties not listed hold none of this flow’s credentials at this point.
Watch out for
- Device-code phishing. An attacker starts the flow themselves and sends the victim the code. The victim approves; the attacker’s agent gets the token. Show the client name, location and requested scopes prominently, and keep codes short-lived.
- If the agent runs on the same machine as a browser, use authorization code with PKCE and a loopback redirect instead. The redirect binds the approval to the session; a typed code does not.
- Polling too fast earns a
slow_downerror. Respectinterval. - The token lands in a headless environment. Plan for where it is stored and how it is revoked when the container goes away.
Device flow or CIBA?
Both decouple the device that needs a token from the device where the person approves. In the device grant the user carries a code from the agent to the server. In CIBA the server reaches out to a user it already knows. Use the device grant to sign in someone who is sitting there; use CIBA to ask a known user for approval when they are somewhere else.
Standards in play
See the full tracker for status and links.
Required
What the flow implements, shows in a step, or must support. These decide its maturity rating.
OAuth 2.0 Authorization Framework
The foundation under MCP authorization and nearly every agent delegation scheme.
Security of Cross-Device Flows
Covers the consent-phishing risks of device codes and backchannel prompts, which is how agents usually reach humans. New in 2026.
Resource Indicators
Required by MCP. An agent talks to many servers; this is what stops a token for one being replayed at another.
Bearer Token Usage
The default way agents present tokens, and the thing proof-of-possession schemes are trying to replace.
Background
Related reading. Not what the flow implements, and not used in a step.
OAuth 2.1
The baseline MCP profiles. Worth knowing that the normative base of most agent authorization is still, formally, a draft.
Related flows
Authorization code + PKCE
The baseline. A person signs in, approves specific scopes, and the agent receives a token that says so.
Human presentStable standards
Backchannel approval (CIBA)
The agent asks the authorization server to go and find the user. Approval arrives as a push notification, not a redirect.
Human reachableStable standards
MCP authorization
How an MCP client that has never seen a server before discovers where to sign in, identifies itself, and gets a token good for that server alone.
Human presentEmerging