Skip to main content
POST
/
api
/
v1
/
auth
/
device
/
start
Device Flow
curl --request POST \
  --url https://api.superbox.ai/api/v1/auth/device/start \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "<string>",
  "device_code": "<string>"
}
'
{
  "device_code": "<string>",
  "user_code": "<string>",
  "verification_uri": "<string>",
  "expires_in": 123,
  "interval": 123
}

​
Overview

The device authorization flow lets the SuperBox CLI authenticate users without embedding browser logic. The CLI obtains a device code, displays a URL for the user to visit, then polls until the user completes login.
This is the flow used internally by superbox auth login --provider google and superbox auth login --provider github.

​
Step 1 - Start Device Session

Request a device code and user code.

​
Endpoint

POST /api/v1/auth/device/start

​
Request Body

​
provider
string
required
OAuth provider: google or github

​
Example Request

curl -X POST https://api.superbox.ai/api/v1/auth/device/start \
  -H "Content-Type: application/json" \
  -d '{"provider": "google"}'

​
Response (200)

​
device_code
string
Internal code used when polling. Keep this private.
​
user_code
string
Short code the user enters on the verification page (e.g., ABCD-1234).
​
verification_uri
string
URL for the user to open in a browser.
​
expires_in
number
Seconds until the device code expires (default: 600).
​
interval
number
Recommended polling interval in seconds (default: 5).
{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "ABCD-1234",
  "verification_uri": "https://superbox.1mindlabs.org/device",
  "expires_in": 600,
  "interval": 5
}

​
Step 2 - User Authorizes

Display the verification_uri and user_code to the user. They open the URL in a browser, log in with the selected provider, and enter the code. 
GET /api/v1/auth/device
This endpoint serves the browser-based verification form. You do not need to call it directly from the CLI.

​
Step 3 - Poll for Token

Poll until the user completes authorization.

​
Endpoint

POST /api/v1/auth/device/poll

​
Request Body

​
device_code
string
required
The device code returned in Step 1

​
Status Codes

StatusMeaning
200Authorization complete. Response contains the token.
428Still waiting. Continue polling.
429Polling too fast. Increase interval.
400Device code expired or invalid.

​
Example Request

curl -X POST https://api.superbox.ai/api/v1/auth/device/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS"}'

​
Success Response (200)

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "AMf-vByW3...",
  "expires_in": 3600,
  "email": "user@example.com",
  "local_id": "abc123def456"
}

​
Pending Response (428)

{
  "status": "pending",
  "message": "Authorization pending"
}