CLI Authentication

Learn how to authenticate the ScaleBox CLI with your API key to securely access templates, sandboxes, and projects. The CLI supports multiple authentication methods including environment variables, command flags, and interactive prompts.

Table of Contents

• API Keys
• Login
• Auth Commands
• Multiple Profiles
• Credential Storage
• Troubleshooting
• Security Best Practices

API Key Types

ScaleBox uses API keys for authentication. Different key types provide different levels of access:

User API Key

Format: sk-abc123def456...

Usage: Regular user operations and template management

Permissions:

• ✅ Read public templates
• ✅ Manage own templates
• ✅ Create sandboxes
• ✅ View own resources

Full secrets are returned only once when a key is created. ScaleBox stores a hash and display prefix server-side.

Authentication Methods

The ScaleBox CLI supports multiple authentication methods with automatic fallback:

1. Browser-Based Authentication (Recommended)

scalebox-cli auth login

The easiest way to authenticate! Simply run the command, and your browser will automatically open for secure authentication:

• Root Users: Sign in with your ScaleBox account credentials
• Organization Members: Use your dedicated signin token
• OAuth Support: Authenticate with GitHub or Google
• CLI tokens: Browser login issues a dedicated sb-cli-... credential (separate from dashboard API keys) and stores it in the active profile
• Manual API keys: Use --api-key sk-... or -i when you prefer a console-created key

2. Environment Variables

SCALEBOX_API_KEY=sk-your-api-key scalebox-cli auth login

Server URL is optional and defaults to https://api.scalebox.dev

3. Command Line Flags

scalebox-cli auth login --api-key sk-1234567890abcdef1234567890abcdef12345678 --server-url https://api.scalebox.dev

Use flags when you need to override environment variables or for automation scripts.

4. Interactive Mode

scalebox-cli auth login -i

The CLI will securely prompt for your API key (hidden input) and server URL with smart defaults.

Authentication Commands

Complete reference for all authentication-related commands:

auth login

Authenticate with ScaleBox using browser-based auth (default) or API key.

Flags:

Example:

scalebox-cli auth login --api-key sk-your-key --server-url https://api.scalebox.dev

auth whoami

Check current authentication status.

Example:

scalebox-cli auth whoami

auth logout

Remove stored authentication credentials for the active profile. If other profiles remain, the CLI switches to another one automatically.

Example:

scalebox-cli auth logout

Multiple Profiles

The CLI supports multiple named credential profiles in one ~/.scalebox-cli/config.json. When you do not explicitly select a profile, commands use current_profile.

Save credentials to a named profile

scalebox-cli auth login --profile staging --api-key sk-your-key --server-url https://api.scalebox.dev

Inspect and switch profiles

scalebox-cli auth profile list
scalebox-cli auth profile use prod
scalebox-cli auth profile remove old-staging

Check config and override the active profile

scalebox-cli auth config
scalebox-cli --profile prod sandbox list

Profile resolution order is root --profile, then SCALEBOX_PROFILE, then current_profile.

Credential Storage

Understanding how the CLI stores and manages your authentication credentials:

📁 Storage Location

• Linux/macOS: ~/.scalebox-cli/config.json
• Windows: %USERPROFILE%\.scalebox-cli\config.json

🔒 File Permissions

• Configuration file is created with 0600 permissions (owner read/write only)
• Directory is created with 0700 permissions (owner access only)

🗃️ Stored Information

• Config format version
• Active current_profile
• Named profiles with API key and server URL

Troubleshooting

❌ "Invalid API key" Error

• Check: Ensure your API key is correct and hasn't been revoked
• Verify: API key format should start with sk-
• Lost key: ScaleBox cannot show the full secret again—create a new key in the dashboard and copy or download it immediately
• Invalid CLI token: Run scalebox-cli auth login again to refresh the browser-issued sb-cli-... credential for the active profile

❌ "Connection refused" Error

• Check: Verify the server URL is correct (https://api.scalebox.dev)
• Network: Ensure you have internet connectivity
• Firewall: Check that HTTPS traffic (port 443) is allowed

❌ "Permission denied" for Operations

• User Key: Check that your API key has the required permissions
• Solution: Contact your account administrator for access
• Check: Run scalebox-cli auth whoami to verify your role

❌ Configuration File Issues

• Reset: Run scalebox-cli auth logout then login again
• Manual cleanup: Delete ~/.scalebox-cli/config.json
• Permissions: Check file permissions allow read/write access

Security Best Practices

✅ Do

• Keep your API keys secure and never share them
• Use appropriate API keys for your operations
• Regularly rotate your API keys
• Log out when finished on shared systems
• Use the CLI on trusted networks

❌ Don't

• Store API keys in version control systems
• Share API keys in chat, email, or documentation
• Use API keys beyond your permission level
• Leave authentication active on public/shared computers
• Ignore permission errors - they indicate security boundaries