Version: 1.9.0

Billing API

One-shot, self-contained spec aligned with ARCH/TECH v9.1.

Highlights:

• Realm:Account = 1:N. X-Realm-Id is the realm scope; account-scoped endpoints require billing_account_id.

• All write endpoints require Idempotency-Key (≈24h TTL). Conflicting body → 409; same body → replay first response.

• Usage events are synchronous: 201 Created (new) or 200 OK (idempotent).

• unit is server-enriched for usage events; subject is attribution only (not in idempotency hash).

• Hourly usage reports are upserted until freeze (provider invoice.finalized + 24h); late data appear via /ops/reconciliations.

• Catalog: realm-scoped, read-only product/price directory (Stripe-mirrored + realm visibility).

• Wallet: centralized ledger with atomic, idempotent consumption; 402 on insufficient balance (hard cap).

• Billing Principal → Billing Account: The server maintains a 1:1 mapping between a remote-managed billing principal (billing_principal_id) and billing_account_id under a realm/strategy. Never trust a client-supplied billing_account_id; derive it from a validated session/token, and 403 on mismatch.

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