Device Sign-In, explained.
An agent on glasses, a phone call or WhatsApp has no browser to send its person through. Device Sign-In is how it signs them in anyway: a link, a short code, and an approval on the person's own phone. This is how it works in Version 1.0, what it looks like on a server that runs it, and why the spec treats it as the second choice.
The Poppy Simulator runs Device Sign-In against any domain. Free, no sign-up.
What is Device Sign-In?
Device Sign-In is one of the two ways a person signs in to a company through their AI agent in the Personal Agent Protocol (Poppy). The agent asks the company for a code and shows the person a link and a short code. The person opens the link on any device, signs in on the company's own page and approves. Meanwhile the agent polls until it receives tokens. It is the OAuth 2.0 device authorization grant (RFC 8628) with four extra rules, and it exists for agents that cannot receive a browser redirect.
How it works
- The agent asks for a code. It sends the company's device authorization endpoint the scopes it needs and a signed statement of who it is.
- The company answers with two codes. A long
device_codethe agent keeps private, and a shortuser_codefor the person, with a link to the company's verification page. - The agent shows the link and the short code. On a screen, as a QR code, in a chat message, or read aloud.
- The person approves on the company's page. They open the link on whatever device they like, sign in the way they always do, check the code matches, read what the agent is asking for, and approve or decline. Their password never goes near the agent.
- The agent polls. Every few seconds it asks the company's token endpoint whether the person has decided. Once they approve, the answer is a refresh token and a short-lived access token.
If you have ever signed a TV in to a streaming service by typing a code on your phone, you have used the same grant.
The requests, on a live server
These are the requests as Stacktree's server takes them. The code and token values are made up. The endpoints, lifetimes and error names are what we serve.
The agent starts:
POST /oauth/device HTTP/1.1
Host: api.stacktr.ee
Content-Type: application/x-www-form-urlencoded
client_id=https://agent.example/agent.json
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOi...
&scope=sites:read The client_id is the address of the agent's metadata document, and the assertion is a JWT signed with a key that document lists. There is no registration step. We answer:
{
"device_code": "pdc_4fKq...",
"user_code": "K7MP-W2QX",
"verification_uri": "https://api.stacktr.ee/device",
"verification_uri_complete": "https://api.stacktr.ee/device?user_code=K7MP-W2QX",
"expires_in": 600,
"interval": 5
} The agent shows the person the link and K7MP-W2QX, then polls:
POST /oauth/token HTTP/1.1
Host: api.stacktr.ee
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=pdc_4fKq...
&client_id=https://agent.example/agent.json
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOi... Until the person decides, each poll gets a 400 with one of these:
| Error | Meaning | What the agent does |
|---|---|---|
authorization_pending | The person has not finished. | Wait interval seconds, poll again. |
slow_down | The agent polled too fast. | Add 5 seconds to the interval from now on. |
access_denied | The person declined. | Stop, and tell them. |
expired_token | Ten minutes passed. | Start again if the person still wants to. |
invalid_grant | The code is unknown, already used, or another agent's. | Stop. |
After an approval, the next poll returns the tokens:
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "pat_9xT...",
"scope": "sites:read"
} The scope in the answer is what the person approved, which can be less than the agent asked for. On our page a person can untick a permission before approving.
What Poppy adds to RFC 8628
Section 4.3 of the 1.0 spec takes the device grant as it is and adds four rules:
- The link has to be on the company's own ground. Before showing it, the agent must check that the link's host is the company's issuer host or its
organization.domain, or a subdomain of either, and must show the company's name and domain with it. Otherwise one company could hand over another company's sign-in page as its own. - Opening the link approves nothing. Neither does scanning the QR code. The person signs in and decides on the page.
- The consent page shows every time. Even when the account has already granted every requested scope to that agent. Every person using an agent shares one
client_id, so "this client was approved before" says nothing about who is asking now. - Every poll carries the client assertion. A stolen
device_codeis useless without the agent's signing key.
One more thing changed on the way to 1.0. Whether a company offers Device Sign-In is no longer a field in poppy.json. An agent reads it from the OAuth server's metadata: the device grant under grant_types_supported, and a device_authorization_endpoint.
Direct Sign-In or Device Sign-In
| Direct Sign-In | Device Sign-In | |
|---|---|---|
| Underlying grant | Authorization code with PKCE | Device authorization grant (RFC 8628) |
| The agent needs | A way to receive a browser redirect | A way to show or speak a link and a code |
| The person | Is sent to the company's page and back | Opens a link on any device and confirms a code |
| How the agent gets tokens | Exchanges the code from the redirect | Polls the token endpoint |
| Always cross-device | No | Yes |
| Standing in the spec | Preferred. A company that offers sign-in should offer it. | Optional. For agents that cannot use Direct. |
The guides go a step further for agents: if you cannot receive the redirect on the device the person is using, first try sending them the Direct Sign-In link, with a redirect address you control. Fall back to Device Sign-In only when that is not possible.
The phishing risk
The spec says it without softening: Device Sign-In "is easier to use for phishing than Direct Sign-In" (4.3). The reason is in the design. Whoever holds the device_code gets the tokens, and nothing in the flow proves that the person approving is the person who asked.
So the attack needs no stolen password. Anyone can run a personal agent, since a client_id is just a URL that serves a metadata document and keys. An attacker starts Device Sign-In with a real company, gets a real link on the company's real domain, and sends it to a customer with a pretext. If the customer approves, the attacker's agent holds tokens for that account. The same trick has been used against the device grant elsewhere, where it is usually called device code phishing.
This is why the spec requires both sides to follow RFC 10027, the best current practice for cross-device flows. For a company that means two things: assess the risk in writing before offering it, and choose mitigations from the RFC's list. Section 10.8 of the spec is plain that the protocol accepts the remaining risk, as OAuth does, and limits it.
What a company has to do
From 4.3 and the company guide:
- Offer Direct Sign-In too. Device Sign-In should not be the only way in.
- Write the risk assessment RFC 10027 section 2 asks for, and pick mitigations from its section 6.1.
- Keep codes short-lived and single-use. About 10 minutes.
- Put the verification page on your issuer's host or your own domain. Agents will not show a link anywhere else.
- Make the page do the work. Name the agent that is asking. Ask the person to confirm the code matches. List every scope. Tell them to decline a code they did not ask for. Offer Decline next to Approve.
- Rate-limit. Return
slow_downto agents that poll faster thaninterval, and limit wrong code entries. - Keep scopes narrow. What an approval reaches is the size of the damage when one is phished.
What an agent has to do
- Use it only when the person signs in themselves. Never type their password, enter their one-time code or click Approve for them.
- Check the link's host against the company's issuer and domain before showing it, and show the company's name and domain with it.
- Show the link and the code.
verification_uri_completeas a link or QR code, anduser_codeas well, so the person can see it matches the page. - Keep
device_codeprivate, and out of the model's context. It is a secret in the same class as a refresh token. - Poll no faster than
interval, and add 5 seconds on everyslow_down.
What our risk assessment found
We turned Device Sign-In on in production on 19 October 2026 and wrote the RFC 10027 assessment on 27 October. Writing it was more useful than we expected, for one reason: it made us list everything an approval reaches.
The finding. Our two scopes cover a person's pages: reading them, and publishing or changing them. But a signed-in agent's token also worked on routes that had nothing to do with pages. It could open the billing portal, start a checkout, and list and delete API keys. No scope said so, and no consent page mentioned it. We fixed that the next day: those routes now return 403 owner_only to any personal agent, whatever its scopes. The bug was not specific to Device Sign-In, but it was the phishing question, "what does one bad approval cost?", that found it.
What we run:
- Codes that last 10 minutes. A
device_codeworks once and is stored only as a keyed hash. - A
user_codeof eight characters from a 31-character alphabet with no look-alikes (no0,O,1,IorL), which is about 40 bits. - Limits of 120 new requests per agent per hour, 30 per network per hour, and 60 code lookups per signed-in person per hour.
- An agent must authenticate with its signed assertion before it can start. That identifies the agent, not the person, so it lets us block an agent but does not stop a malicious one from existing.
- An approval page that names the agent, shows its address with "Only approve it if you recognize it and you just asked it to connect", shows the code, lists the permissions with a tick box each, and grants nothing until the person decides.
- The decision takes the person's session from a request header only, never a cookie, so another page cannot approve on their behalf.
- Every connected agent is listed in the person's account with a Disconnect button, which revokes its refresh token.
What we do not have, and say so in the assessment:
- Proximity checks. RFC 10027 suggests confirming that the two devices are near each other. An agent in a cloud service and a person on their phone share no signal to compare.
- Sender-constrained tokens. Our access tokens are Bearer. The binding is the agent: a refresh token works only with the client assertion of the agent it was issued to.
- A shorter life for device grants. Our refresh tokens last 90 days however the sign-in happened. A shorter life for ones that came from Device Sign-In is the next change we would make.
Why we offer it at all: an agent that lives in WhatsApp or on a phone call can publish with us signed out, but without Device Sign-In it could never act on a person's own pages. And what an approval reaches is pages, not money or account administration.
Should you offer it?
Start with Direct Sign-In. Then ask two questions.
Do the agents your customers use have a browser? An agent in a desktop app or a web chat does, and Direct Sign-In covers it. Agents in messaging apps, on voice calls and on wearables may not.
What does one phished approval cost? If the answer involves money, medical records or control of the account, RFC 10027 advises against the device grant, and the guides say such a company may offer Direct Sign-In only. If the answer is bounded and you can make it smaller with narrow scopes, the trade may be worth it.
To see whether a company offers it, read its OAuth metadata:
curl -s https://api.yourdomain/.well-known/oauth-authorization-server \
| grep -E 'device_authorization_endpoint|device_code' To watch the whole flow, the Poppy Simulator runs Device Sign-In against any domain that serves a poppy.json and shows each request with the rule it tested. For where this fits in a full build, see stage 5 of the implementation guide.
Frequent questions
What is Device Sign-In? +
When does an agent use Device Sign-In instead of Direct Sign-In? +
Is Device Sign-In safe? +
Does a company have to offer Device Sign-In? +
How does an agent know a company offers Device Sign-In? +
How long does a Device Sign-In code last? +
What does Poppy add to the standard device grant? +
Related guides
- Personal Agent Protocol 1.0, explained The whole protocol step by step: discovery, Sessions, sign-in and what 1.0 changed.
- How to implement it as a company The build order, with Device Sign-In as stage 5 and the consent page before it.
- poppy.json, field by field The discovery file, and why sign-in types are no longer in it.
- Personal Agent Protocol vs MCP How Poppy sign-in sits next to an MCP server's OAuth.
- Who supports Poppy Which companies serve a poppy.json today, and on which version.
- Poppy Simulator A hosted test agent that runs both sign-in types against your domain.
Sources and further reading
- Personal Agent Protocol 1.0: Device Sign-In ↗ Section 4.3 of the spec: the grant and the four rules Poppy adds.
- Personal Agent Protocol guides: Device sign-in ↗ What a company should do before and after offering it.
- RFC 8628: OAuth 2.0 Device Authorization Grant ↗ The grant itself: the two codes, polling and the error names.
- RFC 10027: Cross-Device Flows, Security Best Current Practice ↗ The risk assessment and mitigations the spec requires.
- Stacktree's OAuth server metadata ↗ Where an agent reads that we offer the device grant.
An agent can use us before anyone signs in.
Stacktree is a company agents can use today: an agent publishes a private page for its person with no account, and signs them in only when they want the page kept. Over the Personal Agent Protocol, MCP or one HTTP request. Free to start, no card.
Sign up free →