---
title: "Poll a device-code grant for completion"
method: GET
path: "/api/agent/signup/poll"
tags: ["auth"]
---

# Poll a device-code grant for completion

`GET /api/agent/signup/poll`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/agent/signup/poll`
- Auth: none required

Anonymous (the device_code is the credential). Returns `pending`, `completed` (with the minted agent_token — surfaced ONCE), or `cancelled`. After completion the record is consumed and further polls 410.

## Query parameters

- `device_code` string

## Response `200`

Grant status (pending/completed/cancelled) or the self-describe contract.

- SignupPollResponse: One of pending / completed / cancelled. `completed` surfaces the agent_token exactly once.
  - `status` 'pending' | 'completed' | 'cancelled', required
  - `user_id` string
  - `agent_token` string: Plaintext, surfaced ONCE — store it on the agent.
  - `tier` string
  - `pending_tier` string
  - `granted_scopes` string[]
  - `sandbox` boolean: Present + true when the minted token is a sandbox/test-mode token (mirrors the `sandbox` flag sent to /start).
  - `reason` string: On cancellation.
  - `next_steps` object

## Other responses

- `410`: device_code expired, unknown, consumed, or cancelled-and-already-surfaced.
- `500`: Completed record missing token.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)