Authentication API

The Authentication API manages user credentials, tokens, and device authentication for Bootspring CLI and services.

Overview#

Bootspring uses browser-based device flow for CLI authentication, similar to how GitHub CLI and other modern tools authenticate.

Authentication Methods#

1. Device Flow Authentication (Recommended) - Browser-based login for CLI
2. API Key Authentication - Long-lived keys for programmatic access

How Device Flow Works#

1. CLI requests a device code from the server
2. User opens browser to verify the code
3. User authenticates and selects a project
4. CLI polls for completion and receives API key + project info
5. CLI creates local .bootspring.json with project link

Credential Storage#

• Global credentials: ~/.bootspring/credentials.json (shared across all directories)
• Per-directory project link: .bootspring.json (specific to each directory)

All credentials are stored securely with AES-256 encryption.

Device Flow Endpoints#

Request Device Code#

Request a new device code for CLI authentication.

Request Body:

Response:

Poll for Token#

Poll for device authorization token (called by CLI while user authenticates in browser).

Request Body:

Response (Pending):

Response (Success):

REST API Endpoints#

Login#

Authenticate a user and receive access tokens.

Request Body:

Response:

Register#

Create a new user account.

Request Body:

Response:

Get Current User#

Get the currently authenticated user's profile.

Headers:

Response:

Refresh Token#

Refresh an expired access token.

Request Body:

Response:

File Storage#

Bootspring stores authentication data in the following files:

All credential files are created with 0600 permissions (owner read/write only).

Security Features#

Credential Encryption#

Credentials are encrypted using AES-256-CBC with a machine-derived key:

• Key is derived from hostname and username
• Each credential file has a unique initialization vector (IV)
• Encryption is transparent - decryption happens automatically on read

Device Fingerprinting#

Device fingerprinting provides:

• Unique device identification for multi-device management
• Detection of credential copying between machines
• Session security enhancement

Fingerprint components:

• Hostname
• Username
• Platform and architecture
• CPU model
• Home directory path
• Network interface MAC addresses

Error Handling#

Invalid Credentials#

Expired Token#

Invalid Refresh Token#

Best Practices#

1. Use API keys for automation: For CI/CD and scripts, prefer API keys over JWT tokens
2. Rotate API keys regularly: Generate new API keys periodically for security
3. Don't share credentials: Each team member should have their own credentials
4. Use environment variables: Store API keys in environment variables, not in code
5. Handle token refresh: Implement automatic token refresh in long-running applications

CLI Commands#

Per-Directory Project Linking#

Each directory can be linked to a different project:

The .bootspring.json file is created in each directory:

Global vs Local Configuration#