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

For Jenkins specifically, prefer the header instead of the URL:

POST https://app.butterstack.com/webhooks/jenkins
X-Webhook-Token: YOUR_TOKEN

Jenkins jobs that source YOUR_TOKEN from a build parameter (rather than a masked “Secret text” credential) leak it in cleartext to anyone with Jenkins read access, via Jenkins’ own REST API (GET .../api/json?tree=actions[parameters[name,value]]) - see the Jenkins integration guide for the recommended credential setup. The ?token= query-string form still works for Jenkins (and for the other webhook endpoints above), but it also risks landing in request/proxy/access logs, so use it only where a header isn’t practical.

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

Permission Scopes

API tokens can be configured with granular permissions:

Scope	Description	Default
`ping`	Health check: verify the token works.	Yes
`read:projects`	List projects and their metadata.	No
`read:workspace_events`	Read the workspace activity feed (builds, deployments, approvals) for accounts you belong to - cross-project visibility.	No
`read:tasks`	Read tasks and their linked changes, builds, and deployments in projects you are a member of.	No
`write:tasks`	Create and update tasks in projects you belong to.	No
`read:builds`	Read build runs, steps, failure diagnostics, and store deployments in projects you belong to.	No
`write:builds`	Trigger new build runs.	No
`read:assets`	Read assets, their approval records and status, and analysis metadata.	No
`write:assets`	Create approval and denial decisions on assets.	No
`read:members`	List the user ids, roles, and connected-account providers of members in projects you belong to. Returns no names or email addresses.	No
`read:changes`	Read commit and changelist history, including file and approval counts, in projects you belong to.	No

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"
}