OAuth

Start a device sign-in (RFC 8628)

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.

post/oauth/device_authorization

Request

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

Request body

client_idstring required

groundmail-cli, or a client registered with the device_code grant type

scopestring

Space-separated scopes; defaults to full

device_namestring

Shown on the approval page and in Settings → CLIs & agents (e.g. the hostname)

workspacestring

Workspace name or id to preselect on the approval page (a hint, not a grant)

Example request

{
  "scope": "emails:send domains:read"
}

Response

Device sign-in started

device_codestring required
user_codestring required
verification_uristring required
verification_uri_completestring required
expires_ininteger required
intervalinteger required

Minimum seconds between polls

Example response

{
  "user_code": "BCDF-GHJK",
  "expires_in": 600
}

Changes

No recorded changes to this operation across all 2 revisions of this API.