Authentication

BugSpark uses three authentication methods depending on the context:

• Cookie-based auth for the dashboard (browser sessions)
• API key auth for the widget and external integrations
• Personal Access Token (PAT) for the CLI and automation

API Base URL

All API endpoints are prefixed with:

https://api.bugspark.dev/api/v1

For self-hosted instances, replace with your own domain.

Cookie-Based Authentication

The dashboard uses httpOnly cookies for secure session management.

Register

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepassword123"
}

Returns the user object and sets bugspark_access_token and bugspark_refresh_token cookies.

Login

{
  "email": "jane@example.com",
  "password": "securepassword123"
}

Refresh Token

No request body required. The refresh token is read from the bugspark_refresh_token cookie.

Get Current User

Logout

API Key Authentication

The widget and external integrations authenticate using a project API key passed in the X-API-Key header:

curl -X POST https://api.bugspark.dev/api/v1/reports \
  -H "X-API-Key: bsk_pub_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "Button broken", "description": "...", "severity": "high", "category": "bug"}'

API keys are scoped to a single project. You can find your key in the project settings or rotate it via the API.

Personal Access Token (PAT) Authentication

The CLI and CI/CD scripts authenticate using a PAT passed in the Authorization: Bearer header:

curl -X GET https://api.bugspark.dev/api/v1/projects \
  -H "Authorization: Bearer bsk_pat_your_token_here"

PATs are user-scoped and have the same permissions as the user who created them. They bypass CSRF validation automatically.

Create a Token

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

List Tokens

Revoke a Token

See CLI Authentication for the full security model and best practices.

Error Responses

Authentication errors return HTTP 401:

{
  "detail": "Invalid email or password."
}