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

1. Navigate to Project → Integrations
2. Select your integration (Perforce, Jenkins, etc.)
3. Copy the Webhook Token from the integration details

Using the Token

Append the token to your webhook URL. The exact URL for your integration is shown on the integration’s page in ButterStack (Project → Integrations → your integration) - copy it from there rather than assembling it by hand:

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

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

POST https://www.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 Token

1. Go to Settings → API Tokens (/api_tokens)
2. Click Create an API Token
3. Provide a descriptive name (e.g., “Jenkins CI”) and tick the scopes it needs
4. Copy the token from the page you land on right after creating it

The full token value is shown once - on the page you land on immediately after creating it. Copy it then. ButterStack stores only a SHA-256 hash of the token plus its first 8 characters, so the value cannot be recovered afterwards; if you lose it, revoke the token and create a new one.

The CLI and MCP server mint their own tokens through the browser OAuth flow instead; see the CLI Guide.

Using Bearer Tokens

Include the token in the Authorization header:

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

Example Request

curl -X GET \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  https://www.butterstack.com/api/v1/projects/PROJECT_ID/build_runs

Token Types

The two are not interchangeable: a webhook token authenticates a specific integration’s inbound endpoint, an API token authenticates you against the REST API and carries scopes.

Permission Scopes

API tokens can be configured with granular permissions:

A butter auth login (CLI and MCP) token gets every scope above except read:members. read:changes was added to that set later: a CLI token issued before then does not carry it and gets 403 insufficient_scope from the changes endpoints, so run butter auth login again to reissue.

Token Management

Best Practices

• Use descriptive names for tokens
• Rotate tokens periodically
• Use separate tokens for different environments
• Check each token’s Last used timestamp on the API Tokens page
• Revoke unused tokens

Revoking Tokens

1. Go to Settings → API Tokens
2. Open the token to revoke
3. Click Revoke Token
4. Confirm the action

Revoked tokens are immediately invalidated.

Token Creation Notifications

Whenever a new API token is created on your account, ButterStack sends you an email notification. This happens for tokens created either of the two ways described above: through the web UI, or via a CLI/MCP login.

Who receives it: the token owner, always and only. API tokens are personal credentials with no project or account scoping, so nobody else is notified.

What it contains:

• The token’s name
• An 8-character, non-secret prefix of the token (never the full token value)
• The creation method (web UI or CLI/MCP login)
• The creation timestamp, in UTC
• A link to Settings > API Tokens

If it wasn’t you: revoke the token immediately from Settings > API Tokens, then reply to the notification email. Replies reach ButterStack support.

Manage your tokens at Settings > API Tokens.

Error Responses

401 Unauthorized

A 401 from the REST API has an empty body - there is no JSON to parse. Branch on the status code.

Causes:

• Missing or malformed Authorization header
• Unknown or revoked token
• Expired token (CLI/MCP tokens expire after 90 days)

Tokens created before ButterStack started hashing tokens at rest stop working on 05 Oct 2026. If your token predates that change, mint a replacement from /api_tokens and update whatever uses the old one before then.

403 Forbidden

A valid token missing the scope the endpoint requires:

{
  "error": "insufficient_scope",
  "required_scope": "read:builds",
  "token_scopes": ["ping", "read:projects"]
}

A write endpoint called against a read-only (demo or swept-trial) account returns a different 403; see Read-Only Accounts.

Related

• Webhooks Reference - Webhook endpoints and payloads
• REST API - REST API endpoints