---
title: "Begin the RFC 8628 device-code token mint"
method: POST
path: "/api/agent/signup/start"
tags: ["auth"]
---

# Begin the RFC 8628 device-code token mint

`POST /api/agent/signup/start`

## Request

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

Anonymous (per-IP rate limited, 30/hr). Returns a device_code (kept by the agent) + a user_code the human enters at verify_url. Then poll /api/agent/signup/poll until the human approves.

## Request body

- SignupStartRequest
  - `scopes` string[], required: Requested capability scopes (validated against the user's tier at approval).
  - `client_name` string: Free-text agent identifier shown to the approving human.
  - `sandbox` boolean: Mint a sandbox/test-mode token: WRITE verbs return a simulated receipt instead of mutating; reads serve real data. Still a real token with real scopes — this does NOT widen access. Immutable after mint. See the root x-sandbox extension.

## Response `200`

Device-code grant started.

- SignupStartResponse
  - `device_code` string, required: Long secret — the agent keeps it, never displays it.
  - `user_code` string, required: Short human-readable code.
  - `verify_url` string, required
  - `verify_url_complete` string: verify_url + ?code= prefilled.
  - `expires_in` integer, required: Seconds (900).
  - `interval` integer, required: Recommended poll interval in seconds (5).

## Other responses

- `400`: Missing/invalid scopes or malformed body.
- `429`: Per-IP rate limit exceeded.
- `500`: KV write failed.

---

[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)