API
API
Cbox Billing exposes several HTTP surfaces, each with its own auth model and throttle
tier. All the JSON APIs are versioned under /api/v1 and rendered as JSON (the app
forces JSON responses for api/* and webhooks/*).
The surfaces
| Surface | Prefix | Auth | Throttle |
|---|---|---|---|
| Enforcement API | /api/v1 |
Bearer token (api.token) |
cbox-enforcement (600/min) |
| Management API | /api/v1 |
Bearer token (api.token) |
cbox-management (60/min) |
| Hosted checkout & portal | /billing |
Opaque session token in the URL | web |
| Payment webhooks | /webhooks/{gateway} |
Gateway signature | cbox-webhook (120/min) |
| License activation | /api/v1/license |
Deployment id (unauthenticated) | throttle:30,1 |
The enforcement and management APIs share the same token auth and per-org scope; they
differ in throttle tier and in that the management writes honour an
Idempotency-Key.
In this section
| Page | What |
|---|---|
| Authentication | API tokens (operator, per-org, product-scoped), the static token, and per-org enforcement. |
| Enforcement API | leases, reserve, commit, usage, entitlements. |
| Management API | plans, organizations, subscriptions, usage, invoices, payment methods, checkout/portal sessions, intents, licenses. |
| Hosted checkout & portal | The token-authorized pages and their JSON action endpoints. |
| License activation | The optional, unauthenticated heartbeat. |
Idempotency
Mutating management writes that must not double-apply carry the idempotency
middleware and honour an Idempotency-Key request header. A retried
subscribe / plan-change / quantity / add-on / license-issue with the same key
returns the original outcome instead of applying twice. Keys are stored in the
idempotency_keys table. The routes that require it are noted in
Management API.
Throttling
Limits are per bearer token (token:<sha256>), IP as fallback. The three tiers and
their env keys are documented in Configuration → CORS & throttling.