CLI Authentication

Learn how the BugSpark CLI authenticates with the API using Personal Access Tokens (PATs).

How It Works

┌─────────────┐    bsk_pat_...    ┌──────────────┐    SHA-256    ┌──────────┐
│  BugSpark   │ ──────────────→  │  BugSpark    │ ──────────→  │ Database │
│  CLI        │  Authorization:  │  API         │  hash match  │          │
│             │  Bearer token    │              │              │          │
└─────────────┘                  └──────────────┘              └──────────┘

1. You create a PAT in the Dashboard (or via the bugspark login flow)
2. The CLI stores the token locally at ~/.bugspark/config.json
3. Every API request includes the token in the Authorization: Bearer header
4. The API hashes the token with SHA-256 and matches it against the database
5. If valid, the request proceeds as the token owner

Personal Access Tokens (PATs)

PATs are long-lived authentication credentials designed for CLI and API automation.

Token Format

bsk_pat_a1b2c3d4e5f6g7h8i9j0...

• Prefix: bsk_pat_ — allows quick identification
• Body: Cryptographically random string (32+ characters)
• The full token is only shown once at creation time

Security Model

How Tokens Are Verified

When the API receives a request with Authorization: Bearer bsk_pat_...:

1. Extract prefix — the first 16 characters (e.g. bsk_pat_a1b2c3d4)
2. Database lookup — find token records matching this prefix
3. Hash comparison — SHA-256 hash the full token and compare with stored hash
4. Validate expiry — reject if the token has expired
5. Update last used — record the timestamp for audit purposes
6. Return user — attach the token owner to the request context

Local Config File

The CLI stores your credentials at:

~/.bugspark/config.json

Contents:

{
  "apiUrl": "https://bugspark-api.onrender.com/api/v1",
  "token": "bsk_pat_a1b2c3d4..."
}

Security

• File permissions are set to 0600 (read/write only for your user)
• The token is stored in plaintext (same approach as Docker, Vercel, and Sentry CLIs)
• Run bugspark logout to delete the config file

Managing Tokens

In the Dashboard

Go to Settings → Personal Access Tokens to:

• Create new tokens with custom names and expiry dates
• View all tokens — see name, prefix, last used date, and expiry
• Revoke tokens that are no longer needed

Via the API

You can also manage tokens programmatically:

{
  "name": "CI Pipeline Token",
  "expires_in_days": 90
}

Returns the full token (only shown once):

{
  "id": "uuid",
  "name": "CI Pipeline Token",
  "token": "bsk_pat_a1b2c3d4...",
  "prefix": "bsk_pat_a1b2c3d4",
  "expires_at": "2026-05-10T00:00:00Z",
  "created_at": "2026-02-09T00:00:00Z"
}

Comparison with Other Auth Methods

Next Steps

• CLI Commands — Full command reference
• API Authentication — Other authentication methods
• Widget Installation — Set up the widget