Device Authorization | Bootspring Docs

The device authorization flow enables CLI tools and desktop applications to authenticate without requiring users to enter credentials directly in the application.

Overview#

This flow is ideal for:

Command-line tools
Desktop applications
Smart TV apps
IoT devices
Any environment without a browser

Flow Diagram#

┌─────────┐                                    ┌─────────────┐
│  CLI    │                                    │  Bootspring │
│  App    │                                    │  API        │
└────┬────┘                                    └──────┬──────┘
     │                                                │
     │  1. POST /auth/device/code                     │
     │ ─────────────────────────────────────────────► │
     │                                                │
     │  2. Returns device_code, user_code             │
     │ ◄───────────────────────────────────────────── │
     │                                                │
     │  3. Display user_code to user                  │
     │                                                │
     │  ┌─────────────────────────────────────────┐   │
     │  │ User visits bootspring.dev/device       │   │
     │  │ and enters code: ABCD-1234              │   │
     │  └─────────────────────────────────────────┘   │
     │                                                │
     │  4. Poll POST /auth/device/token               │
     │ ─────────────────────────────────────────────► │
     │                                                │
     │  5. Returns access_token (when authorized)     │
     │ ◄───────────────────────────────────────────── │
     │                                                │

Step 1: Request Device Code#

Request#

POST https://api.bootspring.dev/v1/auth/device/code
Content-Type: application/json

{
  "client_id": "bootspring-cli",
  "scope": "read:projects write:projects read:usage"
}

Parameters#

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application identifier
`scope`	string	No	Space-separated list of scopes

Response#

{
  "device_code": "dev_abc123def456...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://bootspring.dev/device",
  "verification_uri_complete": "https://bootspring.dev/device?code=ABCD-1234",
  "expires_in": 900,
  "interval": 5
}

Response Fields#

Field	Description
`device_code`	Code used to poll for authorization
`user_code`	Code the user enters on the website
`verification_uri`	URL where user authorizes the device
`verification_uri_complete`	URL with code pre-filled
`expires_in`	Seconds until codes expire (default: 900)
`interval`	Minimum seconds between poll requests

Step 2: Display to User#

Present the user with clear instructions:

═══════════════════════════════════════════
        Bootspring Device Authorization
═══════════════════════════════════════════

To sign in, visit:

    https://bootspring.dev/device

And enter code:

    ABCD-1234

Or scan this QR code:

    [QR CODE]

Waiting for authorization...
═══════════════════════════════════════════

Best Practices#

Display the code prominently
Show a QR code for verification_uri_complete when possible
Indicate that the app is waiting
Show a countdown for expiration

Step 3: Poll for Token#

Poll the token endpoint at the specified interval.

Request#

POST https://api.bootspring.dev/v1/auth/device/token
Content-Type: application/json

{
  "client_id": "bootspring-cli",
  "device_code": "dev_abc123def456...",
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
}

Pending Response#

{
  "error": "authorization_pending",
  "error_description": "The user has not yet authorized this device"
}

Success Response#

{
  "access_token": "bsd_live_xyz789...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "read:projects write:projects read:usage",
  "refresh_token": "bsr_abc123..."
}

Error Responses#

Error	Description	Action
`authorization_pending`	User hasn't authorized yet	Continue polling
`slow_down`	Polling too fast	Increase interval by 5 seconds
`expired_token`	Device code expired	Restart from step 1
`access_denied`	User denied authorization	Show error to user

Implementation Example#

TypeScript#

// lib/device-auth.ts
interface DeviceCodeResponse {
  device_code: string;
  user_code: string;
  verification_uri: string;
  verification_uri_complete: string;
  expires_in: number;
  interval: number;
}

interface TokenResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  scope: string;
  refresh_token?: string;
}

const API_BASE = 'https://api.bootspring.dev/v1';

export async function requestDeviceCode(
  scope: string = 'read:projects write:projects'
): Promise<DeviceCodeResponse> {
  const response = await fetch(`${API_BASE}/auth/device/code`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'bootspring-cli',
      scope,
    }),
  });

  if (!response.ok) {
    throw new Error('Failed to get device code');
  }

  return response.json();
}

export async function pollForToken(
  deviceCode: string,
  interval: number,
  expiresIn: number
): Promise<TokenResponse> {
  const startTime = Date.now();
  const expiresAt = startTime + expiresIn * 1000;
  let pollInterval = interval * 1000;

  while (Date.now() < expiresAt) {
    await sleep(pollInterval);

    const response = await fetch(`${API_BASE}/auth/device/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: 'bootspring-cli',
        device_code: deviceCode,
        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
      }),
    });

    const data = await response.json();

    if (response.ok) {
      return data as TokenResponse;
    }

    if (data.error === 'slow_down') {
      pollInterval += 5000;
    } else if (data.error === 'authorization_pending') {
      // Continue polling
    } else {
      throw new Error(data.error_description || data.error);
    }
  }

  throw new Error('Device authorization timed out');
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Usage
async function authenticate() {
  const deviceCode = await requestDeviceCode();

  console.log(`Visit ${deviceCode.verification_uri}`);
  console.log(`Enter code: ${deviceCode.user_code}`);

  const token = await pollForToken(
    deviceCode.device_code,
    deviceCode.interval,
    deviceCode.expires_in
  );

  console.log('Authenticated!');
  return token;
}

CLI Example#

// cli/auth.ts
import ora from 'ora';
import open from 'open';
import { requestDeviceCode, pollForToken } from './device-auth';

export async function login() {
  const spinner = ora('Requesting authorization...').start();

  try {
    const deviceCode = await requestDeviceCode();
    spinner.stop();

    console.log('\n╔════════════════════════════════════════╗');
    console.log('║     Bootspring Device Authorization     ║');
    console.log('╠════════════════════════════════════════╣');
    console.log('║                                        ║');
    console.log(`║  Visit: ${deviceCode.verification_uri.padEnd(29)}║`);
    console.log('║                                        ║');
    console.log(`║  Code:  ${deviceCode.user_code.padEnd(29)}║`);
    console.log('║                                        ║');
    console.log('╚════════════════════════════════════════╝\n');

    // Open browser automatically
    await open(deviceCode.verification_uri_complete);

    spinner.start('Waiting for authorization...');

    const token = await pollForToken(
      deviceCode.device_code,
      deviceCode.interval,
      deviceCode.expires_in
    );

    spinner.succeed('Successfully authenticated!');

    // Store token securely
    await storeToken(token);

    return token;
  } catch (error) {
    spinner.fail(`Authentication failed: ${error.message}`);
    throw error;
  }
}

Token Storage#

Store tokens securely on the device:

macOS (Keychain)#

import keytar from 'keytar';

async function storeToken(token: TokenResponse) {
  await keytar.setPassword('bootspring', 'access_token', token.access_token);
  if (token.refresh_token) {
    await keytar.setPassword('bootspring', 'refresh_token', token.refresh_token);
  }
}

async function getToken(): Promise<string | null> {
  return keytar.getPassword('bootspring', 'access_token');
}

Linux (Secret Service)#

// Same API as macOS with keytar

Windows (Credential Manager)#

// Same API as macOS with keytar

Token Refresh#

Refresh tokens before they expire:

POST https://api.bootspring.dev/v1/auth/device/refresh
Content-Type: application/json

{
  "client_id": "bootspring-cli",
  "refresh_token": "bsr_abc123...",
  "grant_type": "refresh_token"
}

Response:

{
  "access_token": "bsd_live_new_token...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "refresh_token": "bsr_new_refresh..."
}

Logout#

Revoke the device token:

POST https://api.bootspring.dev/v1/auth/device/revoke
Authorization: Bearer bsd_live_xyz789...

Security Considerations#

Never store device_code - It's only used during authorization
Store access_token securely - Use system keychain/credential manager
Implement token refresh - Don't wait for expiration
Handle revocation - Check for 401 responses and re-authenticate