---
title: "Approve (or cancel) a pending device-code signup"
method: POST
path: "/api/agent/signup/complete"
tags: ["auth", "browser-session"]
---

# Approve (or cancel) a pending device-code signup

`POST /api/agent/signup/complete`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/agent/signup/complete`
- Auth: API key in cookie `__session`

Clerk-session only - this is the HUMAN half of the RFC 8628 flow, the screen the person lands on after typing the user_code. It binds the device code to the signed-in identity and mints the token. `granted_scopes`, when supplied, must be a subset of what was requested intersected with the tier maximum; omit it to grant exactly that intersection. A `requested_tier` above the caller's current one files a pending operator request rather than granting it. Agents never call this; they poll GET /api/agent/signup/poll.

## Request body

- SignupCompleteRequest
  - `user_code` string, required: The code the human typed in.
  - `granted_scopes` string[]: Explicit subset of requested INTERSECT tier-max. Omit to grant exactly that intersection.
  - `requested_tier` string: Self-declared ring. If above the caller's current tier a pending operator request is filed instead of granted.
  - `tier_request_note` string: Free text shown to the reviewing operator.
  - `action` 'approve' | 'cancel'
  - `cancel_reason` string: Used only when action is `cancel`.

## Response `200`

Approved, or cancelled. The token itself is delivered to the waiting agent through the poll endpoint, never in this response.

- SignupCompleteResponse: The minted token is never in this response — it is delivered to the waiting agent through GET /api/agent/signup/poll.
  - `ok` boolean, required
  - `user_code` string
  - `granted_scopes` string[]
  - `tier` string
  - `pending_tier` string: Present when a tier request was filed for operator review.
  - `status` 'cancelled': Present only on the cancel branch.

## Other responses

- `400`: Malformed body, missing user_code, or granted_scopes outside requested and tier-max.
- `401`: Not signed in.
- `404`: user_code unknown or expired.
- `409`: Already completed or cancelled.

---

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