Authentication
API Keys
All external API requests use the X-API-Key header.
Do not send keys in query parameters
Requests containing api_key, X-API-Key, or x-api-key in the query string are rejected with 400 Bad Request.
Key Format
Gateway keys are generated in the format bach_{environment}_{random}.
| Prefix | Environment |
|---|---|
bach_live_ |
Production |
bach_test_ |
Test |
Scopes
The current public endpoint requires kb:read.
| Scope | Status |
|---|---|
kb:read |
Required for POST /api/v1/ext/kb/query |
admin:* |
Internal/admin use only |
Additional scopes can exist on keys, but only documented public routes enforce them.
Tiers
| Tier | RPM | Burst (10s) | Daily Budget | Monthly Budget |
|---|---|---|---|---|
| Free | 60 | 20 | $5.00 | $25.00 |
| Professional | 300 | 60 | $50.00 | $250.00 |
| Enterprise | 1,000 | 200 | $500.00 | $2,500.00 |
IP Allowlisting
Keys can carry an allowed_cidrs allowlist. When present, requests from IPs outside those CIDRs fail with 403 Forbidden.
Rotation
Admin rotation keeps the old key in rolling status while a replacement key is issued. The overlap window is configurable and defaults to 48 hours in the admin route.
Common Failures
| Status | Meaning |
|---|---|
400 |
Key was supplied in the URL instead of the header |
401 |
Missing, invalid, revoked, or expired API key |
403 |
Missing scope or unauthorized client IP |