API Keys & Webhooks¶

Integrate Bambuddy with external tools using API keys and webhooks.

API Keys¶

Overview¶

API keys allow external applications to:

• Access Bambuddy data
• Trigger actions
• Integrate with automation tools

Creating an API Key¶

1. Go to Settings > API Keys
2. Click Create API Key
3. Enter a name (e.g., "Home Assistant")
4. Select permissions
5. Click Create
6. Copy the key immediately - it won't be shown again!

Permissions¶

Available Permissions¶

Principle of Least Privilege¶

Only grant permissions that are needed:

• Read-only for dashboards
• Control for automation
• Admin only when necessary

Using the API¶

Authentication¶

Include the API key in request headers:

curl -H "X-API-Key: your-api-key-here" \
  http://localhost:8000/api/v1/printers

Base URL¶

http://your-server:8000/api/v1

Common Endpoints¶

See API Reference for complete documentation.

Webhooks¶

Outgoing Webhooks¶

Bambuddy can send notifications to external URLs:

1. Go to Settings > Notifications
2. Add a Webhook provider
3. Enter your endpoint URL
4. Configure events to trigger

Payload Format¶

{
  "event": "print_complete",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "printer": "Workshop X1C",
    "filename": "benchy.3mf",
    "duration": 8100,
    "filament_used": 45.2,
    "status": "success"
  }
}

Events¶

Integration Examples¶

Home Assistant¶

Use REST sensors to display status:

sensor:
  - platform: rest
    name: "Bambuddy Printer Status"
    resource: "http://bambuddy:8000/api/v1/printers/1/status"
    headers:
      X-API-Key: "your-api-key"
    value_template: "{{ value_json.state }}"
    json_attributes:
      - progress
      - remaining_time
      - temperature

Trigger automations on webhook events.

Node-RED¶

Use HTTP request nodes with API key authentication.

IFTTT / Zapier¶

Use webhook triggers and actions.

Managing API Keys¶

Viewing Keys¶

See all API keys in Settings:

• Name
• Created date
• Last used
• Permissions

Revoking Keys¶

Delete keys that are no longer needed:

1. Find the key in the list
2. Click Delete
3. Confirm deletion

Key is immediately invalidated.

Rotating Keys¶

Best practice: Rotate keys periodically:

1. Create new key
2. Update applications
3. Delete old key

Security Best Practices¶

Key Storage¶

• Never commit keys to version control
• Use environment variables
• Store in secrets managers

Network Security¶

• Use HTTPS for external access
• Limit API access to trusted IPs if possible
• Consider VPN for remote access

Monitoring¶

• Review API key usage
• Check for unauthorized access
• Revoke unused keys

Permissions¶

• Use minimum required permissions
• Create separate keys per application
• Avoid using admin keys in automation

Rate Limiting¶

Current Limits¶

Rate Limit Headers¶

Responses include rate limit info:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705331400

Troubleshooting¶

401 Unauthorized¶

• Check API key is correct
• Verify key hasn't been revoked
• Ensure header name is X-API-Key

403 Forbidden¶

• Check key has required permissions
• Verify endpoint matches permissions

429 Too Many Requests¶

• Rate limit exceeded
• Wait and retry
• Check for runaway automation

Tips¶