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#

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_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#

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