Skip to content
← Cbox Billing 0.1.0 View on GitHub

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.

The contract & SDK

The /api/v1 surface is described by a hand-authored OpenAPI 3.1 contract, served live and kept in lock-step with the routes by a drift test. Read it, or a typed client, before you write a line of integration:

  • GET /api/openapi.yaml · GET /api/openapi.json — the machine-readable contract.
  • GET /api/docs — a self-contained HTML reference (also linked from the console command palette and Settings → API tokens).
  • A typed TypeScript SDK under sdks/typescript/.

See OpenAPI spec & live reference for the full story.

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.
OpenAPI spec & live reference The OpenAPI 3.1 contract, /api/openapi.{yaml,json}, /api/docs, and the drift guard.
TypeScript SDK The typed client under sdks/typescript/ — install, config, and transport features.

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.