Authentication

All BuildButler API requests require authentication. The API supports two authentication methods: API tokens and OAuth 2.0.

API tokens

API tokens are the simplest way to authenticate. Generate one from Settings → API → Create Token.

Include the token in the Authorization header:

curl -H "Authorization: Bearer bb_live_abc123def456" \
  https://buildbutler.example.com/api/v1/jobs

Token scopes

Scope	Description
`read:jobs`	List and read job details
`read:builds`	List and read build details and logs
`read:analytics`	Access analytics and export data
`write:connections`	Create and update Jenkins connections
`write:alerts`	Create and update alert rules
`admin`	Full access (includes all scopes)

When creating a token, select only the scopes you need. Tokens with fewer permissions are safer to distribute.

Token format

Tokens are prefixed for easy identification:

bb_live_ — production token
bb_test_ — test/staging token

OAuth 2.0

For applications that act on behalf of a user, use the OAuth 2.0 authorization code flow.

1. Register your application

Go to Settings → API → OAuth Apps → New App and provide:

App name — displayed on the consent screen
Redirect URI — where to send the user after authorization

You'll receive a Client ID and Client Secret.

2. Authorization request

Redirect the user to:

GET https://buildbutler.example.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:jobs read:builds

3. Exchange the code for a token

curl -X POST https://buildbutler.example.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/callback

Response:

{
  "access_token": "bb_live_xyz789",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "bb_refresh_abc123"
}

4. Refresh the token

curl -X POST https://buildbutler.example.com/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=bb_refresh_abc123 \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

Rate limits

Tier	Requests per minute
Free	60
Pro	300
Enterprise	1000

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1705312400

Authentication

On this page