Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is the device code flow?

The device code flow is the OAuth grant from RFC 8628 for machines that cannot open a browser or take typed input: servers, containers, TVs. The device shows a short code and a link; you open the link on any other device, sign in, and type the code. Meanwhile the device polls the token endpoint until the token arrives.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

A machine with no browser shows you a code; you approve on another device while it polls the authorization server for the token.a server, a container,an SSH sessionthe machineno browseryou, with a phoneor laptopauthorization servercodes expire,then start again1. asks for a device code2. code + link to visit3. shows you the code4. open link, type code5. polls, then gets token
  1. The machine POSTs to the device authorization endpoint with its client_id and the scopes it wants.

  2. The server returns a device_code, a short user_code, a verification_uri, how long they last, and a polling interval (5 seconds if none is given).

  3. The machine prints the link and the code. For Intraface, npx intraface login --device does this on a box with no browser.

  4. You open the link on your phone or laptop, sign in, type the code, and approve what the machine asked for.

  5. The machine polls the token endpoint with the device_code grant type; it gets authorization_pending until you finish, then the token.

  6. slow_down means wait 5 more seconds between polls; access_denied or expired_token ends the attempt.

Source: RFC 8628: OAuth 2.0 Device Authorization Grant

Device code flow versus the browser flow

The authorization code flow assumes the thing signing in can open a browser and receive a redirect. A build server, a Docker container, a machine you reach over SSH, or a TV cannot. RFC 8628 turns the problem around: instead of sending the device to the browser, it sends you. The device asks the authorization server for a pair of codes and shows you the short one with a link. You open the link on a phone or laptop, sign in there, and type the code. The device never sees your password and never needs a redirect URI, because nothing is sent back to it; it simply asks the token endpoint, again and again, whether you have finished yet.

The trade is friction for reach. Typing a short code is slower than clicking Allow, but it works on any machine that can print text and make an outbound HTTPS request.

Example: signing in from a server with no browser

You are logged in to a remote box over SSH and want an agent there to work on a shared board. Running npx intraface login tries to open a browser, which does nothing useful on a headless machine. Running npx intraface login --device instead starts the device flow: the CLI prints a link and a code, you open the link on the laptop you are typing from, sign in, enter the code, and approve. The CLI, which has been polling in the background, receives a token and stores it. From then on pull and publish work exactly as they would on your own machine.

When to use it

Use the device code flow when the client has no browser or no usable keyboard: CI runners, containers, kiosks, SSH sessions, media players. Do not use it as a shortcut on a normal laptop; the browser flow is faster and lets the server check a redirect URI. The spec asks that the verification link be short and easy to remember, since people may have to type it, and allows a verification_uri_complete that bakes the code in, for QR codes and the like.

Common mistakes

  • Polling too fast. Respect the interval in the response, 5 seconds if none is given, and add 5 seconds whenever the server answers slow_down. Ignoring this gets a client blocked.
  • Treating authorization_pending as an error. It means "not yet". Keep polling until you see a token, access_denied, or expired_token.
  • Letting the codes outlive the session. They expire; expires_in tells you when. Start over rather than reusing an old device_code.
  • Typing a code someone sent you. The flow can be phished: an attacker starts it and asks you to enter their code. Only enter codes from a screen you are looking at, and read what the approval page says is being authorized.

FAQ

Does the device code flow need PKCE?
No. PKCE protects an authorization code that travels back through a browser redirect. In the device code flow nothing is redirected: the device_code goes straight from the authorization server to the device over TLS, and only the device ever holds it.
Is the device code flow part of MCP?
Not in the core spec. MCP authorization defines the browser-based authorization code flow. OAuth 2.1 names the device grant as an extension grant, so a CLI can use it to obtain a token and then present that token to an MCP server as an ordinary bearer token.
Can the device code flow be phished?
Yes. RFC 8628 warns that an attacker can start the flow on their own device and email you the link and code; if you enter it, their device is signed in as you. Only type a code shown on a screen in front of you, and read what the approval page says is being authorized.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.