Begin a CLI device-authorization flow
curl -X POST 'https://dashboard.justcrawl.io/api/v1/cli-auth/start' \ -H 'Content-Type: application/json' \ -d '{"hostname":"raj-laptop"}'import os, socket, requests, timestart = requests.post( 'https://dashboard.justcrawl.io/api/v1/cli-auth/start', json={'hostname': socket.gethostname()},).json()print(f"Open {start['verification_uri_complete']} and approve {start['user_code']}")# then poll with start['device_code'] via POST /cli-auth/pollimport os from 'node:os';const start = await (await fetch('https://dashboard.justcrawl.io/api/v1/cli-auth/start', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ hostname: os.hostname() }),})).json();console.log(`Open ${start.verification_uri_complete} and approve ${start.user_code}`);RFC 8628 device-authorization-grant — first leg. Mints a
(device_code, user_code) pair: the CLI keeps the device_code secret
and polls /cli-auth/poll, the human-readable user_code is shown to
the user who pastes it into the browser at verification_uri. The
device_code is hashed (SHA-256) before storage so a DB leak cannot
impersonate an in-flight CLI session. The user_code uses a confusion-
free 20-letter alphabet (no 0/O/1/I/L) and is formatted XXXX-YYYY
for easy reading aloud. interval: 2 is the recommended poll cadence
in seconds. The flow expires after 10 minutes — re-call /start to
restart. This is the endpoint jc auth login --browser (master plan
Phase 0.5) hits first.
Request Body
Section titled “Request Body ”object
Display string shown on the browser confirm page (e.g. raj-laptop). Sanitized to strip control characters and pipes. Defaults to unknown CLI and is capped at 120 chars.
Example generated
{ "hostname": "example"}Responses
Section titled “ Responses ”Pending device code created.
object
64-char hex secret the CLI keeps and polls with. Never shown to humans.
Human-typeable code in XXXX-YYYY format. Shown to the user; pasted in browser.
Dashboard URL the user opens to approve.
Same URL pre-filled with the user_code + hostname querystring.
TTL in seconds (currently 600).
Recommended poll interval in seconds.
Example generated
{ "device_code": "example", "user_code": "example", "verification_uri": "example", "verification_uri_complete": "example", "expires_in": 1, "interval": 1}Validation failed — request body or query is missing/invalid
object
Example
{ "error": "Missing or invalid \"url\" field"}Unexpected server error. Logs and PostHog $exception capture
object
Example
{ "error": "Something went wrong"}