---
title: "Start an OAuth 2.0 Device Authorization Grant (RFC 8628-shaped) flow (T453)"
method: POST
path: "/auth/device/start"
tags: ["Auth"]
---

# Start an OAuth 2.0 Device Authorization Grant (RFC 8628-shaped) flow (T453)

`POST /auth/device/start`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/auth/device/start`
- Auth: none required

Public, no request body. Lets a headless/CLI environment that cannot open a browser (an SSH box, a headless Claude Code session) begin obtaining a ContextQ API key: mints a `device_code` (an opaque polling secret used by POST /auth/device/token) and a short human-typable `user_code`, both returned to the caller exactly once. The human opens `verification_uri` (or `verification_uri_complete`, which pre-fills the `user_code`), signs in, and approves the device via the dashboard against a chosen workspace; the caller meanwhile polls /auth/device/token with `device_code` until it receives the minted key. Rate limited to 10 requests / 5 minutes per IP. See `src/services/device-authorization.service.ts` for the full flow.

## Response `200`

Device authorization started.

- object
  - `device_code` string: Opaque polling secret for POST /auth/device/token. Shown once.
  - `user_code` string: Human-typable code the user enters at verification_uri, formatted XXXX-XXXX.
  - `verification_uri` string, uri
  - `verification_uri_complete` string, uri: verification_uri with user_code pre-filled as a query param.
  - `expires_in` integer: Seconds until device_code/user_code expire (10 minutes).
  - `interval` integer: Minimum seconds between polls before the client must slow_down.

## Other responses

- `429`: Rate limit exceeded for this endpoint.

---

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