Device Authorization Flow

The Device Authorization Grant (RFC 8628) is built for devices that can't easily present a browser or accept text input — CLIs, smart TVs, IoT gateways. The device displays a short code; the user enters it on a phone or laptop to complete login.

Where it's used

3SO's own ssoctl CLI tool uses this flow for ssoctl auth login — the terminal shows a URL and code, you approve it in a browser tab, and the CLI receives a token without ever seeing your password.

1. Device Authorization Request

The device requests a device code and a short user code from the authorization server.

POST /oauth2/device/authorize
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&
scope=read write

2. Device & User Codes

The server responds with a device_code (used by the device to poll) and a short user_code the person types into a verification page.

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://sso.example.com/device",
  "verification_uri_complete": "https://sso.example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

3. User Verification

The person opens verification_uri on any browser (phone, laptop), enters the user code, logs in, and approves the request — including any MFA challenge.

// Display to the user:
// "Go to sso.example.com/device and enter code WDJB-MJHT"

4. Token Polling

Meanwhile, the device polls the token endpoint at the given interval until the user approves (or the code expires).

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&
client_id=YOUR_CLIENT_ID

// Returns "authorization_pending" until the user approves,
// then a normal token response.