Device Authorization
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
Loading code block...
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
client_id | string | Yes | Your application identifier |
scope | string | No | Space-separated list of scopes |
Response
Loading code block...
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_completewhen 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
Loading code block...
Pending Response
Loading code block...
Success Response
Loading code block...
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
Loading code block...
CLI Example
Loading code block...
Token Storage
Store tokens securely on the device:
macOS (Keychain)
Loading code block...
Linux (Secret Service)
Loading code block...
Windows (Credential Manager)
Loading code block...
Token Refresh
Refresh tokens before they expire:
Loading code block...
Response:
Loading code block...
Logout
Revoke the device token:
Loading code block...
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