Device flow

The device flow connects an agent that cannot open a browser, such as a sandboxed cloud agent or a CI job. It follows RFC 8628. The agent asks the relay for a short code and shows it to the user. The user approves the request on the Mac, and the agent collects its tokens by polling. This page documents the three routes of the flow: the device authorization request, the activation page and the device grant of the token request. The step-by-step for a person setting this up is in Device flow. The examples use $RELAY as defined in Relay API.

Before you start#

• The relay is paired with at least one Mac. See Pairing and devices.
• The client is registered with the device grant. See POST /register. A client that only uses the device flow sends no redirect_uris.

Concepts#

The flow has four steps.

1. The agent calls POST /device_authorization and receives a device_code, a user_code and an interval.
2. The agent shows the user_code and the name of the Mac to the user.
3. The user approves on the Mac: a banner with Approve and Deny, or Settings > Cloud > Connector approvals, or the relay's /activate page.
4. The agent polls POST /token every interval seconds until it gets tokens or an error that ends the flow.

The tokens that come out are the same as in the browser flow. An approved connector works until revoked, its tokens never expire and are never rotated, and expires_in is ten years. See Token lifetime. A repeated poll after approval returns tokens again.

Endpoints#

POST /device_authorization#

Starts the device flow for an agent that has no usable browser. The reply holds a short user_code that the agent shows to the user, and a device_code that the agent keeps and polls with. At the same moment, Herald shows an approval banner on the Mac.

Request

The body is a form. A confidential client also sends its secret.

curl -s -X POST "$RELAY/device_authorization" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d client_id=hc_3fa91c0de27b45a6d1180123456789ab \
  -d scope=notify

{
  "device_code": "hrv_...",
  "user_code": "BDFG-HJKM",
  "verification_uri": "https://herald-relay.example.workers.dev/activate",
  "verification_uri_complete": "https://herald-relay.example.workers.dev/activate?user_code=BDFG-HJKM",
  "expires_in": 600,
  "interval": 5,
  "device_name": "Studio Mac",
  "device_count": 1,
  "device_index": 1,
  "device_online": true
}

Response fields

Errors

Notes

• Tell the user which Mac will show the banner: device_name says so.
• The user sees a banner with the code and Approve and Deny. Settings > Cloud > Connector approvals lists the request with the code in large type and, in small type, a 6-digit approval code for the web page.
• Asking again with the same client takes over the open request. The earlier device_code stops working.
• The request lasts 10 minutes. After approval, the agent has 5 minutes to collect the tokens.
• At most 3 approvals wait on one Mac at once, and at most 12 are begun an hour.

GET /activate#

Serves the page where a person with a browser enters the agent's code and approves it. The page is optional: the user can approve from the banner in Herald instead. The page asks for the user_code the agent printed, then for the 6-digit approval code that Herald shows.

Request

curl -s "$RELAY/activate?user_code=BDFG-HJKM" -H "User-Agent: Herald-Agent/1.0"

Example response

The reply is an HTML page with status 200.

HTTP/2 200
content-type: text/html; charset=utf-8

<h1>Approve an agent</h1>

Errors

Notes

• A wrong or expired user_code shows the entry page again with a note. It is never an error status.
• The fifth wrong approval code denies the request.

The page posts to three helper routes. They belong to the page and are not an API for clients.

POST /token#

Collects the tokens of an approved device request. This is the device grant of the token endpoint. Send grant_type=urn:ietf:params:oauth:grant-type:device_code and poll no faster than interval. The other grants, the shared fields and the token reply are documented under POST /token.

Request

The body is a form.

curl -s -X POST "$RELAY/token" \
  -H "User-Agent: Herald-Agent/1.0" \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=hc_3fa91c0de27b45a6d1180123456789ab \
  -d device_code=hrv_...

Example response

Once the user has approved, the reply is 200:

{
  "access_token": "hra_...",
  "token_type": "Bearer",
  "expires_in": 315360000,
  "refresh_token": "hrr_...",
  "scope": "notify"
}

While the user has not answered, the reply is 400:

{
  "error": "authorization_pending",
  "error_description": "waiting for the user to approve in Herald"
}

Response fields

The fields of the success reply are in POST /token.

Errors

A failed poll is 400 with {"error": "...", "error_description": "..."}, except client authentication, which is 401.

Notes

• Poll no faster than interval. The first poll must also wait interval seconds after the request started, or it gets slow_down.
• A poll that gets slow_down or authorization_pending is not fatal. Only access_denied, expired_token and invalid_grant end the flow.
• A repeated poll after approval, for example after a lost response, returns tokens again. It never undoes the approval.
• Approval creates one agent key for the connector, named after client_name, with notify scope. It appears in Settings > Cloud > Agent keys and can be revoked there. The access token works on every agent endpoint and on /mcp.

Related#

• Device flow: the task page for connecting an agent without a browser.
• Relay OAuth endpoints: registration, the browser flow, refresh and revocation.
• Relay API: credentials and the error shape.
• Cloud and the relay: what the relay is and how it is hosted.