Authentication
The billing API supports two authentication methods: JWT Bearer tokens and API keys.
JWT Bearer Token
For most integrations, use a short-lived JWT signed with HS256:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
JWTs must include:
sub— customer or user IDexp— expiration timestamp (max 1 hour for customer tokens, 8 hours for admin tokens)scope—customeroradmin
The JWT signing secret is configured via JWT_SECRET environment variable.
API Keys
Long-lived API keys are supported for server-to-server integrations:
X-API-Key: bsk_live_xxxxxxxxxxxxxxxxxxxx
API keys are validated in constant time to prevent timing attacks. Prefix bsk_live_ for production, bsk_test_ for sandbox.
Route Security
| Route prefix | Required scope |
|---|---|
GET /health | None (public) |
GET /openapi.json | None (public) |
/v1/* | customer or admin |
/admin/v1/* | admin only |
Environment Variables
| Variable | Description |
|---|---|
JWT_SECRET | HMAC-SHA256 secret for JWT signing/verification |
API_KEY_HASH | SHA-256 hex of the valid API key |
STRIPE_WEBHOOK_SECRET | Stripe webhook signing secret (whsec_...) |