Version: 1.11.0

Billing API

Billing API reference for catalog, subscriptions, usage, wallet, and supporting workflows.

Highlights:

• Realm scoping: send X-Realm-Id on every request. Runtime endpoints require X-Principal-Id and X-User-Id; account-scoped billing endpoints use their documented billing account inputs.
• Realm admin: send X-Realm-Admin: true for realm-wide admin RLS where applicable.
• Idempotency: write endpoints require Idempotency-Key as a transport request identity. The HTTP layer does not cache responses; durable replay and conflicting-body checks are endpoint-specific and occur inside the owning domain transaction where documented.
• Usage events are synchronous: 201 Created for new events or 200 OK for idempotent replays.
• Usage reports are upserted until billing freezes; late data appears in reconciliation views if enabled.
• Catalog is realm-scoped and read-only. Wallet consumption is atomic and idempotent; insufficient balance returns 402.
• Billing principal to billing account mapping: the server derives billing_account_id from your authenticated principal. If you supply billing_account_id, it must match or the request is rejected.

Authentication

HTTP: Bearer Auth

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

API Key: serviceAuth

Service-to-service HMAC. Authorization: SVC-AUTH keyId=<KEY_ID>,sig=<BASE64>,ts=<ISO8601>,nonce=<UUID>,alg=HMAC-SHA256. Body integrity via'Content-Digest: sha-256=:<BASE64(SHA256(raw_body_bytes))>:'

Security Scheme Type:	apiKey
Header parameter name:	Authorization

License