---
title: "Start a device sign-in (RFC 8628)"
method: POST
path: "/oauth/device_authorization"
tags: ["OAuth"]
---

# Start a device sign-in (RFC 8628)

`POST /oauth/device_authorization`

## Request

- Base URL: `https://api.groundmail.dev`
- URL: `https://api.groundmail.dev/oauth/device_authorization`
- Auth: none required

Public and rate limited. Returns a secret `device_code` to poll `/oauth/token` with, and a short `user_code` the person approves at `verification_uri_complete`. The approval page shows the client, the device name and the scopes asked for, and the person picks the workspace. Form-encoded (RFC 8628) or JSON bodies are accepted.

## Request body

- DeviceAuthorizationRequest
  - `client_id` string, required: `groundmail-cli`, or a client registered with the device_code grant type
  - `scope` string: Space-separated scopes; defaults to `full`
  - `device_name` string: Shown on the approval page and in Settings → CLIs & agents (e.g. the hostname)
  - `workspace` string: Workspace name or id to preselect on the approval page (a hint, not a grant)

## Response `200`

Device sign-in started

- DeviceAuthorizationResponse
  - `device_code` string, required
  - `user_code` string, required
  - `verification_uri` string, required
  - `verification_uri_complete` string, required
  - `expires_in` integer, required
  - `interval` integer, required: Minimum seconds between polls

## Other responses

- `400`: `invalid_request`, `invalid_scope` or `unauthorized_client`
- `401`: `invalid_client`: unknown client_id
- `429`: Rate limited (`Retry-After`)

---

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