Authentication API | Bootspring Docs

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

Overview#

Bootspring supports two authentication methods:

JWT Token Authentication - Session-based authentication with refresh tokens
API Key Authentication - Long-lived keys for programmatic access

All credentials are stored securely in ~/.bootspring/ with AES-256 encryption.

REST API Endpoints#

POST /api/v1/auth/login

Authenticate a user and receive access tokens.

Request Body:

{
  "email": "user@example.com",
  "password": "your-password",
  "deviceContext": {
    "deviceId": "device-uuid",
    "platform": "darwin",
    "arch": "arm64"
  }
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": "15m",
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "tier": "pro"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Register#

POST /api/v1/auth/register

Create a new user account.

Request Body:

{
  "email": "user@example.com",
  "password": "secure-password",
  "name": "John Doe"
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": "15m",
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "tier": "free"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Get Current User#

GET /api/v1/auth/me

Get the currently authenticated user's profile.

Headers:

Authorization: Bearer YOUR_TOKEN

Response:

{
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "John Doe",
    "tier": "pro",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Refresh Token#

POST /api/v1/auth/refresh

Refresh an expired access token.

Request Body:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": "15m"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

JavaScript/Node.js API#

Module Import#

const auth = require('bootspring/core/auth');

Credential Management#

`getCredentials()`#

Get stored credentials (decrypted).

const credentials = auth.getCredentials();
// Returns: { token, refreshToken, expiresAt, user, apiKey }

`saveCredentials(credentials)`#

Save credentials with encryption.

auth.saveCredentials({
  token: 'jwt-token',
  refreshToken: 'refresh-token',
  expiresAt: '2024-01-15T12:00:00Z',
  user: { id: 'user_123', email: 'user@example.com', tier: 'pro' }
});

`clearCredentials()`#

Clear all stored credentials (logout).

auth.clearCredentials();

Token Management#

`getToken()`#

Get the current JWT token if valid.

Returns: Token string or null if expired/not present.

const token = auth.getToken();
if (token) {
  // Use token for API requests
}

`getApiKey()`#

Get the stored API key.

const apiKey = auth.getApiKey();

`getRefreshToken()`#

Get the refresh token.

const refreshToken = auth.getRefreshToken();

`isApiKeyAuth()`#

Check if using API key authentication.

if (auth.isApiKeyAuth()) {
  console.log('Using API key authentication');
}

Authentication State#

`isAuthenticated()`#

Check if user is authenticated (valid token or API key).

if (auth.isAuthenticated()) {
  console.log('User is logged in');
} else {
  console.log('Please log in');
}

`getUser()`#

Get the current user's profile.

const user = auth.getUser();
// Returns: { id, email, tier, ... } or null

`getTier()`#

Get the user's subscription tier.

const tier = auth.getTier();
// Returns: 'free', 'pro', 'team', or 'enterprise'

`login(response)`#

Save login response from JWT authentication.

auth.login({
  token: 'jwt-token',
  refreshToken: 'refresh-token',
  expiresIn: '15m',
  user: { id: 'user_123', email: 'user@example.com', tier: 'pro' }
});

`loginWithApiKey(apiKey, user)`#

Save API key authentication.

auth.loginWithApiKey('bs_live_abc123...', {
  id: 'user_123',
  email: 'user@example.com',
  tier: 'pro'
});

`updateTokens(response)`#

Update tokens after refresh.

auth.updateTokens({
  token: 'new-jwt-token',
  refreshToken: 'new-refresh-token',
  expiresIn: '15m'
});

`logout()`#

Clear all credentials and log out.

auth.logout();

Device Fingerprinting#

`generateDeviceFingerprint()`#

Generate a unique device fingerprint based on machine characteristics.

const fingerprint = auth.generateDeviceFingerprint();
// Returns: SHA-256 hash of device characteristics

`getDeviceInfo()`#

Get or create persistent device information.

Returns: Device info object that persists across sessions.

const deviceInfo = auth.getDeviceInfo();
// Returns:
// {
//   deviceId: 'uuid',
//   fingerprint: 'sha256-hash',
//   createdAt: '2024-01-15T10:30:00Z',
//   platform: 'darwin',
//   arch: 'arm64',
//   hostname: 'my-macbook'
// }

`getDeviceId()`#

Get just the device ID.

const deviceId = auth.getDeviceId();

`getDeviceContext()`#

Get full device context for authentication requests.

const context = auth.getDeviceContext();
// Returns:
// {
//   deviceId: 'uuid',
//   platform: 'darwin',
//   arch: 'arm64',
//   hostname: 'my-macbook',
//   cliVersion: '1.2.0',
//   nodeVersion: 'v20.10.0',
//   timezone: 'America/New_York'
// }

`clearDeviceInfo()`#

Clear device info (for testing or reset).

auth.clearDeviceInfo();

Configuration#

`getConfig()`#

Get global Bootspring configuration.

const config = auth.getConfig();

`saveConfig(config)`#

Save global configuration.

auth.saveConfig({
  defaultProject: '/path/to/project',
  theme: 'dark'
});

`getCredentialsPath()`#

Get the path to the credentials file.

const path = auth.getCredentialsPath();
// Returns: '/Users/username/.bootspring/credentials.json'

Constants#

`BOOTSPRING_DIR`#

Path to Bootspring's config directory.

const { BOOTSPRING_DIR } = require('bootspring/core/auth');
// Returns: '/Users/username/.bootspring'

File Storage#

Bootspring stores authentication data in the following files:

File	Purpose
`~/.bootspring/credentials.json`	Encrypted user credentials
`~/.bootspring/config.json`	Global configuration
`~/.bootspring/device.json`	Device fingerprint and ID

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#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid email or password"
  }
}

Expired Token#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token has expired"
  }
}

Invalid Refresh Token#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired refresh token"
  }
}

Best Practices#

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

CLI Commands#

# Login with email/password
bootspring auth login

# Login with API key
bootspring auth login --api-key YOUR_API_KEY

# Check authentication status
bootspring auth status

# Logout
bootspring auth logout

# Show credentials file location
bootspring auth path