By · Founder, Stacktree · Last updated
Personal Agent Protocol · sign-in

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

  1. 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.
  2. The company answers with two codes. A long device_code the agent keeps private, and a short user_code for the person, with a link to the company's verification page.
  3. The agent shows the link and the short code. On a screen, as a QR code, in a chat message, or read aloud.
  4. 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.
  5. 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:

ErrorMeaningWhat the agent does
authorization_pendingThe person has not finished.Wait interval seconds, poll again.
slow_downThe agent polled too fast.Add 5 seconds to the interval from now on.
access_deniedThe person declined.Stop, and tell them.
expired_tokenTen minutes passed.Start again if the person still wants to.
invalid_grantThe 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_code is 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-InDevice Sign-In
Underlying grantAuthorization code with PKCEDevice authorization grant (RFC 8628)
The agent needsA way to receive a browser redirectA way to show or speak a link and a code
The personIs sent to the company's page and backOpens a link on any device and confirms a code
How the agent gets tokensExchanges the code from the redirectPolls the token endpoint
Always cross-deviceNoYes
Standing in the specPreferred. 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_down to agents that poll faster than interval, 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_complete as a link or QR code, and user_code as well, so the person can see it matches the page.
  • Keep device_code private, 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 every slow_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_code works once and is stored only as a keyed hash.
  • A user_code of eight characters from a 31-character alphabet with no look-alikes (no 0, O, 1, I or L), 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.

FAQ

Frequent questions

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. The agent asks the company for a code, shows the person a link and a short code, and the person approves on the company's own page on any device. It is the OAuth 2.0 device authorization grant (RFC 8628) with four extra rules.
When does an agent use Device Sign-In instead of Direct Sign-In? +
When it cannot receive a browser redirect: an agent on glasses, a speaker, a phone call, or inside a chat app such as WhatsApp. The spec prefers Direct Sign-In, and the guides tell an agent to first try sending the person the Direct Sign-In link with a redirect address it controls. Device Sign-In is the fallback when that is not possible.
Is Device Sign-In safe? +
It is easier to use for phishing than Direct Sign-In. Whoever holds the device code gets the tokens, so an attacker can start a request and persuade someone to approve it. The spec requires companies and agents to follow RFC 10027, and a company limits the damage with short single-use codes, narrow scopes, rate limits and a consent page that names the agent.
Does a company have to offer Device Sign-In? +
No. A company that offers sign-in should offer Direct Sign-In. Device Sign-In is optional, and the guides say a company whose accounts hold sensitive or high-value resources, such as a bank, may offer Direct Sign-In only.
How does an agent know a company offers Device Sign-In? +
From the company's OAuth server metadata, not from poppy.json. The server lists urn:ietf:params:oauth:grant-type:device_code under grant_types_supported and gives a device_authorization_endpoint. Earlier drafts had an auth.device field in poppy.json. That was removed in 0.3.
How long does a Device Sign-In code last? +
The company chooses, and says so in expires_in. The guides suggest about 10 minutes, which is what Stacktree uses. The agent polls no faster than the interval the company returns, usually 5 seconds, and adds 5 seconds whenever the company answers slow_down.
What does Poppy add to the standard device grant? +
Four rules. The agent shows the link only if it is on the company's issuer host or its domain, with the company's name and domain beside it. Opening the link must not approve anything by itself. The company should show its consent page every time, even for scopes approved before. And every poll carries the agent's signed client assertion.
Keep reading

Related guides

References

Sources and further reading

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 →