---
title: "Start a device authorization flow"
method: POST
path: "/v1/auth/device"
tags: ["Account"]
---

# Start a device authorization flow

`POST /v1/auth/device`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/auth/device`
- Auth: none declared

Issues a device code and user code so a CLI or headless client can sign in through the browser. Claim flows may attach an explicit server-side claim handoff.

## Request body

- object
  - `clientId` 'spacefast-cli' | 'spacefast-mcp': Spacefast client starting the flow, shown on the verification page. Omit it unless you are the Spacefast MCP server.
  - `access` 'read' | 'agent' | 'agent-personal-pages': Access profile the device requests. One word with a server-owned meaning; the approver can narrow the resulting scopes on the verification page but never widen them.
  - `claim` object: Explicit claim handoff intent. Only claim flows send this; ordinary device login leaves it absent.
    - `spaceId` string, required: Anonymous space id being claimed with this device flow.
    - `claimToken` string, required: Anonymous Space key. Stored server-side only as a hash.

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `deviceCode` string, required: High-entropy bearer capability the device polls with. Never log or display it.
    - `userCode` string, required: Short display code the user types on the dashboard verification page.
    - `verificationUrl` string, uri, required: Dashboard verification page URL where the user approves this device.
    - `interval` integer, required: Minimum number of seconds the device must wait between polls.
    - `expiresAt` string, date-time, required: Instant after which the device and user codes are no longer redeemable.
  - `requiresAction` object
    - `actionType` 'device_authorization' | 'confirmation' | 'elevation', required: Stable identifier for the out-of-band step that blocks the flow.
    - `instruction` string, required: The step a person must complete out of band.
    - `url` string, uri, nullable: Where to send the human to complete the step, when a destination exists.
    - `pollUrl` string, uri: Where to POST the continuationToken to poll this flow: `/v1/actions/resume`.
    - `continuationToken` string, required: Short-lived, principal-scoped capability for this flow. Present it to POST /v1/actions/resume to poll and complete. Single-use on completion. A secret: never log it.
    - `pollAfterSeconds` integer, required: Minimum seconds to wait before calling resume again.
    - `expiresAt` string, date-time, required: Deadline for the human step. Resume after this returns terminal `expired`; the token survives a short grace so resume can say so, but the flow can no longer be redeemed.

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)