API Authentication

Learn how to authenticate with the BugBrain API using service keys and Bearer tokens.

Service Keys

BugBrain uses service keys for API authentication. Service keys are long-lived credentials that grant access to your organization’s data.

Service Key Format

Service keys follow this format:

bugbrain_sk_[environment]_[random]

Example:

bugbrain_sk_prod_abc1234def5678ghi9jkl0mnopqrst123456uvwxyz

Components:

bugbrain_ — BugBrain service key prefix
sk_ — Service key identifier
prod / dev — Environment (production or development)
Random string — Unique key identifier (base58 encoded)

Key Environments

Environment	Use Case	Restrictions
Production (`prod`)	API calls in production	Full API access, rate limited per plan
Development (`dev`)	Local development, testing	Limited rate limits, no billing charges

⚠️

Never commit service keys to git. Always store them in environment variables or secure secret managers.

Creating Service Keys

Via Dashboard

Go to Settings → API Keys
Click Generate New Key
Enter:
- Key Name — For your reference (e.g., “CI/CD Token”, “Mobile App”)
- Environment — Production or Development
- Expires — Optional expiration date
- Scopes — (Future feature) Granular permissions
Click Generate
Copy the key immediately — It won’t be shown again!

Key Limits

Maximum keys per organization: 10 active keys
Key expiration: Optional (default: no expiration)
Rotation recommended: Every 90 days for production keys

Via API

You can programmatically create keys:

curl -X POST https://api.bugbrain.tech/api/service-keys \
  -H "Authorization: Bearer $EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Integration",
    "environment": "prod",
    "expires_in_days": 90
  }'

Response:

{
  "id": "sk_prod_xyz789",
  "key": "bugbrain_sk_prod_abc1234def5678ghi9jkl0mnopqrst",
  "name": "CI/CD Integration",
  "created_at": "2025-03-08T10:30:00Z",
  "expires_at": "2025-06-06T10:30:00Z",
  "last_used": null
}

Using Service Keys

In HTTP Headers

Add the service key to the Authorization header:

curl https://api.bugbrain.tech/api/test-cases \
  -H "Authorization: Bearer bugbrain_sk_prod_abc1234..."

In Environment Variables

Store keys in environment files:

# .env
BUGBRAIN_API_KEY=bugbrain_sk_prod_abc1234def5678ghi9jkl0mnopqrst

Then use in your application:

# Python
import os
api_key = os.getenv('BUGBRAIN_API_KEY')
 
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

// JavaScript
const apiKey = process.env.BUGBRAIN_API_KEY;
 
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

Request Example

curl -X GET https://api.bugbrain.tech/api/projects \
  -H "Authorization: Bearer bugbrain_sk_prod_abc1234..." \
  -H "Content-Type: application/json"

Key Security

Best Practices

Use Environment Variables — Never hardcode keys
Rotate Regularly — Every 90 days for production
Limit Scope — Use separate keys for different services
Monitor Usage — Check “Last Used” timestamp
Revoke Immediately — If compromised

Detecting Compromised Keys

If you suspect a key is compromised:

Revoke immediately: Settings → API Keys → Delete
Create new key: Generate replacement key
Update integrations: Update CI/CD pipelines, services, etc.
Check usage logs: Review access logs for unauthorized activity

Secure Storage

Local Development:

# .env (gitignored)
BUGBRAIN_API_KEY=bugbrain_sk_dev_...

GitHub Secrets:

# .github/workflows/test.yml
env:
  BUGBRAIN_API_KEY: ${{ secrets.BUGBRAIN_API_KEY }}

GitLab CI Variables:

# .gitlab-ci.yml
variables:
  BUGBRAIN_API_KEY: $BUGBRAIN_API_KEY  # Set in CI/CD variables

Docker Secrets:

# Dockerfile
RUN --mount=type=secret,id=bugbrain_key \
    BUGBRAIN_API_KEY=$(cat /run/secrets/bugbrain_key)

Key Metadata

Viewing Keys

List all active keys:

curl https://api.bugbrain.tech/api/service-keys \
  -H "Authorization: Bearer $KEY"

Response:

{
  "keys": [
    {
      "id": "sk_prod_abc123",
      "name": "CI/CD Integration",
      "environment": "prod",
      "created_at": "2025-02-01T10:00:00Z",
      "expires_at": "2025-05-02T10:00:00Z",
      "last_used": "2025-03-07T15:30:00Z",
      "usage_count": 1250
    },
    {
      "id": "sk_dev_xyz789",
      "name": "Local Development",
      "environment": "dev",
      "created_at": "2025-01-01T10:00:00Z",
      "expires_at": null,
      "last_used": "2025-03-08T09:00:00Z",
      "usage_count": 542
    }
  ]
}

Key Information

Field	Meaning
id	Internal key ID (not the actual key)
name	Human-friendly label
environment	prod or dev
created_at	When key was generated
expires_at	Expiration date (null = no expiration)
last_used	Last API call timestamp
usage_count	Total API calls made

Rate Limiting

API calls are rate-limited per service key:

Plan	Requests/Minute	Requests/Hour	Requests/Day
Starter	30	500	5,000
Growth	60	1,000	10,000
Pro	120	5,000	50,000

Rate limit headers in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1741606800

If rate limited:

{
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Retry Strategy:

import time
import requests
 
MAX_RETRIES = 3
for attempt in range(MAX_RETRIES):
    response = requests.get(
        'https://api.bugbrain.tech/api/executions',
        headers={'Authorization': f'Bearer {api_key}'}
    )
 
    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        print(f"Rate limited. Waiting {retry_after}s...")
        time.sleep(retry_after)
        continue
 
    return response.json()

Error Responses

401 Unauthorized

{
  "error": "invalid_api_key",
  "message": "API key is invalid or expired"
}

Causes:

Key doesn’t exist
Key was revoked
Key expired
Typo in key

403 Forbidden

{
  "error": "insufficient_permissions",
  "message": "Your plan doesn't have access to this resource"
}

Causes:

API access requires upgrade
Team size limit exceeded
Quota exceeded

500 Internal Server Error

{
  "error": "internal_server_error",
  "message": "An unexpected error occurred"
}

Troubleshooting:

Check API status: status.bugbrain.tech
Retry with exponential backoff
Contact support if persists

Key Rotation Example

Best practice: Rotate keys quarterly.

Generate new key: bugbrain_sk_prod_new...
Update CI/CD: Use new key in pipelines
Monitor old key: Wait 7 days to ensure all integrations switched
Revoke old key: Delete it from Settings → API Keys

Overview Executions API