Authentication

Authenticate with the BambooSnow API using API keys or OAuth tokens.

API Keys

API keys are the recommended way to authenticate programmatic access.

Creating an API Key

1. Go to Settings > API Keys
2. Click Create New Key
3. Enter a description
4. Select the scopes (permissions)
5. Click Create
6. Copy and securely store the key

Using API Keys

Include the key in the Authorization header:

curl https://api.bamboosnow.com/v1/repositories \
  -H "Authorization: Bearer bs_live_abc123..."

Key Prefixes

| Prefix | Environment | |--------|-------------| | bs_live_ | Production | | bs_test_ | Test/sandbox |

Scopes

| Scope | Access | |-------|--------| | read | Read-only access to resources | | write | Create and modify resources | | admin | Full access including settings | | agents:run | Execute agents | | agents:configure | Configure agents | | repositories:manage | Connect/disconnect repos |

# Create key with specific scopes
curl -X POST https://api.bamboosnow.com/v1/api-keys \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "name": "CI Pipeline Key",
    "scopes": ["read", "agents:run"]
  }'

OAuth 2.0

For user-facing applications, use OAuth 2.0.

Authorization Flow

1. Redirect user to authorization URL
2. User approves access
3. Receive authorization code
4. Exchange code for access token

Step 1: Redirect to Authorization

https://bamboosnow.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=read%20write&
  state=random-state-string&
  response_type=code

Step 2: Handle Callback

Your callback URL receives:

https://your-app.com/callback?
  code=AUTH_CODE&
  state=random-state-string

Step 3: Exchange Code for Token

curl -X POST https://bamboosnow.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://your-app.com/callback"

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Refreshing Tokens

curl -X POST https://bamboosnow.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Security Best Practices

Key Storage

• Never commit API keys to source control
• Use environment variables or secret managers
• Rotate keys periodically

Key Rotation

# Create new key
NEW_KEY=$(curl -X POST .../api-keys | jq -r '.key')

# Update your systems to use new key
# ...

# Delete old key
curl -X DELETE .../api-keys/OLD_KEY_ID

Minimum Permissions

Only request scopes you need:

# Bad: requesting admin when you only need read
scopes: ["admin"]

# Good: requesting only what's needed
scopes: ["read", "agents:run"]

Rate Limits

API requests are rate limited:

| Plan | Requests/minute | Requests/hour | |------|-----------------|---------------| | Free | 60 | 1,000 | | Team | 300 | 10,000 | | Enterprise | Custom | Custom |

Rate limit headers:

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

When rate limited:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 30
}

Error Responses

| Status | Meaning | |--------|---------| | 401 | Invalid or missing authentication | | 403 | Insufficient permissions | | 429 | Rate limit exceeded |

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_KEY"
}