Device Authorization Flow

OAuth 2.0 device flow for CLI authentication

POST https://api.superbox.ai/v1/auth/device-flow

Device Authorization Flow

cURL

curl --request POST \
  --url https://api.superbox.ai/v1/auth/device-flow \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "<string>",
  "scope": "<string>",
  "device_code": "<string>"
}
'

200

{
  "device_code": "<string>",
  "user_code": "<string>",
  "verification_uri": "<string>",
  "verification_uri_complete": "<string>",
  "expires_in": 123,
  "interval": 123
}

Overview

Device authorization flow enables CLI tools and devices without browsers to authenticate users securely.

This is the authentication method used by SuperBox CLI (superbox auth)

Flow Steps

1. Request Device Code

   CLI requests device and user codes

   POST /auth/device-flow/request
   
2. Display Codes

   CLI displays verification URL and user code Visit: https://superbox.ai/device Enter code: ABCD-1234

3. User Authorization

   User visits URL, logs in, and enters code

4. Poll for Token

   CLI polls token endpoint until authorized

   POST /auth/device-flow/token
   

Request Device Code

Endpoint

POST /auth/device-flow/request

Request Body

client_id · string · required

Client application ID

scope · string

Requested permissions (space-separated) Default: read write

Example Request

cURL
curl -X POST https://api.superbox.ai/v1/auth/device-flow/request \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "superbox-cli",
    "scope": "read write"
  }'

Response (200)

device_code · string

Device verification code (internal use)

user_code · string

User-friendly code to display (e.g., “ABCD-1234”)

verification_uri · string

URL for user to visit

verification_uri_complete · string

URL with code pre-filled

expires_in · number

Code expiration time in seconds (default: 600)

interval · number

Polling interval in seconds (default: 5)

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "ABCD-1234",
  "verification_uri": "https://superbox.ai/device",
  "verification_uri_complete": "https://superbox.ai/device?code=ABCD-1234",
  "expires_in": 600,
  "interval": 5
}

Poll for Token

Endpoint

POST /auth/device-flow/token

Request Body

device_code · string · required

Device code from previous step

client_id · string · required

Client application ID

Example Request

cURL
curl -X POST https://api.superbox.ai/v1/auth/device-flow/token \
  -H "Content-Type: application/json" \
  -d '{
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "client_id": "superbox-cli"
  }'

Success Response (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "rt_abcdef123456...",
  "scope": "read write"
}

Pending Response (428)

{
  "error": "authorization_pending",
  "message": "User has not completed authorization yet"
}

Error Responses

400 - Expired Code

{
  "error": "expired_token",
  "message": "Device code has expired"
}

Complete Implementation

Python CLI
import requests
import time
import webbrowser

def device_flow_auth(): # Step 1: Request device code
response = requests.post(
'https://api.superbox.ai/v1/auth/device-flow/request',
json={'client_id': 'superbox-cli', 'scope': 'read write'}
)
data = response.json()

    device_code = data['device_code']
    user_code = data['user_code']
    verification_uri = data['verification_uri_complete']
    interval = data['interval']

    # Step 2: Display code and open browser
    print(f"\nVisit: {data['verification_uri']}")
    print(f"Enter code: {user_code}\n")

    webbrowser.open(verification_uri)

    # Step 3: Poll for token
    while True:
        time.sleep(interval)

        response = requests.post(
            'https://api.superbox.ai/v1/auth/device-flow/token',
            json={
                'device_code': device_code,
                'client_id': 'superbox-cli'
            }
        )

        if response.status_code == 200:
            token_data = response.json()
            print("✓ Authentication successful!")
            return token_data['access_token']

        elif response.status_code == 428:
            print("Waiting for authorization...")

        elif response.status_code == 429:
            # Slow down polling
            interval += 5

        else:
            print(f"Error: {response.json()['message']}")
            return None

# Usage

token = device_flow_auth()