⌘K

API Authentication

All ButterStack API endpoints require authentication. This guide covers the authentication methods available.

Webhook Authentication

Webhooks use token-based authentication via query parameters.

Obtaining a Webhook Token

Navigate to Project Settings > Integrations
Select your integration (Perforce, Jenkins, etc.)
Copy the Webhook Token from the integration details

Using the Token

Append the token to your webhook URL:

POST https://app.butterstack.com/webhooks/perforce?token=YOUR_TOKEN
POST https://app.butterstack.com/webhooks/jenkins?token=YOUR_TOKEN
POST https://app.butterstack.com/webhooks/jira?token=YOUR_TOKEN

Token Security

Tokens are project-specific
Regenerate tokens if compromised
Use HTTPS for all webhook requests
Store tokens securely in your CI/CD system

REST API Authentication

The REST API uses Bearer token authentication.

Obtaining an API Key

Go to Account Settings > API Keys
Click Generate New Key
Provide a descriptive name (e.g., “Jenkins CI”)
Copy the key immediately (it won’t be shown again)

Using Bearer Tokens

Include the token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.butterstack.com/v1/projects

Example Request

curl -X GET \
  -H "Authorization: Bearer bsk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  https://api.butterstack.com/v1/builds

Token Types

Type	Format	Use Case
Webhook Token	`wh_*`	Inbound webhooks from tools
API Key	`bsk_live_*`	REST API requests
Test Key	`bsk_test_*`	Development/testing

Token Management

Best Practices

Use descriptive names for keys
Rotate keys periodically
Use separate keys for different environments
Monitor key usage in the dashboard
Revoke unused keys

Revoking Keys

Go to Account Settings > API Keys
Find the key to revoke
Click Revoke
Confirm the action

Revoked keys are immediately invalidated.

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing authentication token"
}

Causes:

Missing token in request
Invalid or revoked token
Token doesn’t match the project

403 Forbidden

{
  "error": "forbidden",
  "message": "Token does not have permission for this action"
}