Device Authorization

The device authorization flow allows the CLI to authenticate users who may not be able to paste credentials directly. It follows RFC 8628.

Flow

1. CLI requests a device code
2. CLI opens browser and displays a human-readable code
3. User signs in and enters the code in the browser
4. CLI polls until authorization completes

---

POST /auth/device/code

Request a new device code. No authentication required.

Request

No body required.

Response

{
  "device_code": "a1b2c3d4e5f6...40chars",
  "user_code": "ABCD-1234",
  "verification_uri": "https://app.skillett.dev/device",
  "expires_in": 900,
  "interval": 5
}

Field	Type	Description
device_code	string	40-character hex code for polling
user_code	string	Human-readable code to display (format: XXXX-XXXX)
verification_uri	string	URL where user enters the code
expires_in	number	Seconds until the code expires (900 = 15 min)
interval	number	Minimum polling interval in seconds

Example

$ curl -X POST https://api.skillett.dev/auth/device/code

---

POST /auth/device/authorize

Called by the browser after the user enters their code. Requires user authentication (session/JWT from the dashboard).

Request

{
  "user_code": "ABCD-1234"
}

Response

{
  "status": "authorized"
}

Errors

Code	Error	Description
400	bad_request	Invalid or expired user code
401	unauthorized	User not signed in

---

POST /auth/device/token

Called by the CLI to poll for authorization completion. No authentication required.

Request

{
  "device_code": "a1b2c3d4e5f6...40chars"
}

Response — Pending

{
  "status": "pending",
  "error": "authorization_pending"
}

Response — Authorized

{
  "status": "complete",
  "user": {
    "email": "david@example.com",
    "display_name": "David"
  },
  "api_keys_url": "https://app.skillett.dev/dashboard/api-keys"
}

Response — Expired

{
  "status": "expired",
  "error": "expired_token"
}

Errors

Code	Error	Description
400	bad_request	Invalid device code
400	expired_token	Device code has expired (15 min TTL)
400	already_used	Device code has already been consumed
404	not_found	Device code not found

Example

$ curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"device_code":"a1b2c3d4e5f6..."}' \
    https://api.skillett.dev/auth/device/token