Skip to main content

Identifiers and lifecycles

This page defines the identifiers you must keep stable and the minimal lifecycle rules you should follow in production.

The five identifiers you will see everywhere​

realm_id​

  • What it is: the project boundary.
  • Who chooses it: you (per application).
  • Rule: every request must include X-Realm-Id.

Service key (service_key_id, service_key_secret)​

  • What it is: server-to-server credentials used to authenticate calls to /mgt/v1.
  • Who uses it: your backend services and trusted workers only.
  • Rule: never ship the secret to browsers, mobile apps, or other untrusted clients.

principal_id​

  • What it is: your billing principal identifier (usually a customer, org, team, or tenant id).
  • Who chooses it: you.
  • Rules:
    • It must be stable over time.
    • It must represent the entity that owns billing in your product.
    • Do not use a per-request random id.

billing_account_id​

  • What it is: Vluna's billing account identifier and the account-scoped data anchor.
  • Who assigns it: Vluna.
  • Rules:
    • The mapping between principal_id and billing_account_id is 1:1.
    • The mapping is immutable after first creation.
    • Do not trust client-supplied billing_account_id from untrusted environments.

Idempotency-Key​

  • What it is: a client-provided key used to safely retry write requests.
  • Rules:
    • All write requests require it.
    • Reuse the same key only when retrying the same logical operation.
    • If you reuse a key with a different request body, the server returns a conflict.

Minimal lifecycle: from principal to bearer token​

The simplest safe pattern is:

  1. Your backend receives a request for a customer.
  2. Your backend identifies principal_id for that customer.
  3. Your backend calls POST /mgt/v1/token/issue.
  4. Vluna returns:
    • billing_account_id (stable for that principal)
    • access_token (short-lived bearer token)
  5. Your backend stores principal_id -> billing_account_id in your database.
  6. Your frontend uses the bearer token for /api/v1 calls, when needed.

Minimal lifecycle: authorize then commit​

The runtime gate loop is:

  1. Authorize: POST /mgt/v1/gate/authorize returns a lease_token.
  2. Do the protected work in your system.
  3. Commit: POST /mgt/v1/gate/commits reports usage and returns an authoritative priced result.
  4. If work fails, cancel the lease using POST /mgt/v1/gate/cancel (best-effort).

Safe defaults for Day 0 integration​

Use these defaults until you are ready to tighten enforcement:

  • Always send an Idempotency-Key and reuse it on retries.
  • Start with one stable feature_code and one stable unit for quantity_minor.
  • Treat hints as machine-readable signals: log them, emit metrics, and decide how to degrade behavior when they appear.

Common failure modes (and how to avoid them)​

  • Wrong principal_id choice:
    • Too broad (one id for all customers) merges billing and limits for unrelated customers.
    • Too narrow (random id per request) fragments billing and makes operations and support impossible.
  • Secret handling mistakes:
    • Shipping a Service Key secret to the browser makes account takeover likely.
  • Retry mistakes:
    • Retrying writes without reusing the same Idempotency-Key can double charge or double record usage.

Next steps​