Tenancy: realm, billing account, and billing user
Vluna uses two distinct scopes. Do not mix them up.
Concepts
| Concept | Identifier | Meaning |
|---|---|---|
| Realm | realm_id | Project boundary. All data is isolated by realm. |
| Billing account | billing_account_id | Payor/account boundary for billing details, invoices, payments, subscriptions, checkout, portal, contracts, and account administration. |
| Billing user | billing_user_id | Runtime subject for usage, grants, wallet balance, limits, events, and self-service reports under a billing account. |
Request scoping (HTTP)
Every request must include:
X-Realm-Id: <realm_id>
Runtime requests include both principal and user context:
X-Principal-Id: <principal_id>X-User-Id: <user_id>
Account/payor-scoped requests include account context, typically via:
X-Principal-Id: <principal_id>and/orX-Billing-Account-Id: <billing_account_id>
For public /api/v1 endpoints, the bearer token is issued for a principal and
user and carries the resolved billing account and billing user scope.
What should be constant vs per request
| Field | Typical source | Changes when |
|---|---|---|
realm_id | app config | only when you switch environments (dev, staging, prod) |
| service key | server config | rotates over time |
principal_id | your app request context | changes per customer |
billing_account_id | mapping table or token issue response | changes per customer |
user_id | your app request context | changes per end user |
billing_user_id | token issue response or admin/ops response | changes per end user under an account |
Next
- Mapping rules: Identity mapping: principal to billing account
- Identifiers and lifecycles: Identifiers and lifecycles