---
title: "Start a device authorization"
method: POST
path: "/auth/device/code"
tags: ["Device authorization"]
---

# Start a device authorization

`POST /auth/device/code`

## Request

- Base URL: `https://dungbeetle.dev`
- URL: `https://dungbeetle.dev/auth/device/code`
- Auth: none required

An agent starts the RFC 8628-shaped flow here (no credential required),
shows the human the `user_code` / `verification_uri`, then polls
`/auth/device/token`. Rate-limited per IP.

## Request body

- object
  - `label` string: Agent display name, shown to the approving human.
  - `scopes` AgentScope[]: Requested scopes. Defaults to the Triage preset (runs:read, baselines:read, analytics:read, reviews:write).

## Response `200`

Authorization created.

- object
  - `device_code` string, required: High-entropy redemption secret. Keep private.
  - `user_code` string, required: Short human code, shown as XXXX-XXXX.
  - `verification_uri` string, required
  - `verification_uri_complete` string, required
  - `expires_in` integer, required: Seconds until the code expires (10 minutes).
  - `interval` integer, required: Minimum polling interval in seconds.

## Other responses

- `400`: Invalid body or parameter (`code: validation_error`), or — on screenshot upload — a body that does not hash to the digest (`code: digest_mismatch`).
- `429`: Too many failed attempts or uploads from this client (`code: rate_limited`). Honor the `Retry-After` header; successful authenticated requests never count toward the limit.

---

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