---
title: "Start a device sign-in (the CLI)"
method: POST
path: "/auth/device"
---

# Start a device sign-in (the CLI)

`POST /auth/device`

## Request

- Base URL: `https://api.spacecontext.app/v1`
- URL: `https://api.spacecontext.app/v1/auth/device`
- Auth: none required

A terminal that has no browser session asks for a code. It shows `user_code` and `verification_url` to the person, who opens the console and types the code (never a link with the code in it: a link could be sent by someone else to get their terminal approved), then polls `POST /auth/device/token` with `device_code` every `interval` seconds. The code lives `expires_in` seconds. Public; limited per IP.

## Request body

- DeviceStartRequest
  - `name` string: What is asking, shown to the person: "CLI on MacBook". Default "CLI".
  - `mode` 'live' | 'test': The mode of the key asked for (the person can change it). Default live.

## Response `201`

Codes for the terminal and the person

- DeviceStart
  - `device_code` string, required: The terminal's secret: never shown to the person.
  - `user_code` string, required
  - `verification_url` string, uri, required: The console page where the person types the code.
  - `expires_in` integer, required
  - `interval` integer, required: Seconds between polls.

## Other responses

- `400`: Error response
- `429`: Too many requests. Retry after the number of seconds in `Retry-After`.

---

[API](https://skmtc.dev/spacecontext/apis/space-context-api.md) · [All operations](https://skmtc.dev/spacecontext/apis/space-context-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacecontext/apis/space-context-api/revisions/1dca940259b4?raw)