Skip to main content

Authorize

Scope​

This page defines authorize-time admission behavior and lease issuance rules. For a read-only decision before beginning work, see Preflight.

Inputs and prerequisites​

  • Realm and billing account context must be present.
  • Idempotency-Key is required.
  • Caller identity subject is required.
  • feature_code must be a valid identifier.
  • estimated_quantity_minor is optional and must be non-negative when provided.
  • lease is optional. It must be a unique, non-empty opaque reference within the current billing account and user when provided.
  • budget is optional and names a caller-owned Budget reference, not the internal budget_id.

Decision sequence​

  1. Resolve feature and feature family.
  2. Enforce entitlement for the feature/family.
  3. Resolve active policy windows for the current bundle.
  4. Evaluate quota/rate admission.
  5. Evaluate budget/funding feasibility in prepaid mode.
  6. Issue or reuse the requested lease lifecycle and return lease + window bounds.

Lease issuance rules​

  • A lease is issued only if feature is active, entitlement allows access, and at least one quota window exists for the feature.
  • lease is optional on the request. When supplied, Vluna preserves it exactly; when omitted, Vluna generates an opaque reference.
  • Reauthorizing the same active lease with the same immutable binding returns the original authorization without repeating rate/admission side effects.
  • Reusing an active lease with another binding returns GATE.LEASE_CONFLICT; terminal references return GATE.LEASE_FINALIZED and cannot be reused.
  • Unknown features may be auto-registered when auto-registry is enabled; otherwise authorize rejects unknown features.
  • Lease metadata carries:
    • feature and feature family
    • quota/rate window metadata
    • optional labels
    • hint snapshot for replay consistency
  • Lease TTL follows the deployment policy for gate session duration.

Idempotency behavior​

  • Reusing the same key with the same request hash returns the existing lease response.
  • Reusing the same key with a different request hash returns conflict (409).

Budget and funding semantics​

  • If the caller provides budget, authorize resolves that opaque external reference and evaluates the current Budget headroom snapshot.
  • In prepaid mode, billable admission requires both the authoritative wallet balance and any selected Budget headroom to cover one quantity_minor at the feature's current effective primary activity-meter rate.
  • The minimum admission funding is ceil(unit_price_xusd / unit_quantity_minor). It is independent of estimated_quantity_minor.
  • Estimated funding shortfalls remain advisory and never change admission.
  • A zero-priced primary meter is not balance-limited. Missing pricing remains an accepted outcome with a pricing configuration hint.
  • Funding and budget hints are muted in non-prepaid billing modes.

Advisory meter coverage​

GET /limits/meters?expand[]=coverage can estimate how much usage the current funding or Budget snapshot covers. This is advisory preflight information; it does not reserve value and must not replace authorize or commit.

  • balance_limited=false means the resolved price is zero, so XUSD balance is not the limiting factor. Both quantity estimates are null.
  • max_quantity_minor_estimated is the conservative integer estimate.
  • optimistic_quantity_minor includes the amount that may become payable when the exact-rational remainder is carried forward. It can be null unless the optimistic profile was requested.
  • basis=budget requires a Budget selection; the response still exposes the resolved internal budget_id for operations and diagnostics.

Hint semantics at authorize​

Common hint families:

  • quota.remaining
  • rate.limit
  • funding.xusd_shortfall
  • budget.shortfall
  • pricing.not_configured
  • pricing.meter_price_missing
  • pricing.contract_term_invalid

Recommended handling for these hints is documented in Hints and failure semantics.

Failure semantics​

  • 400: missing required transport input (for example idempotency key).
  • 401: missing auth context.
  • 402: blocked by quota/budget/funding policy.
  • 403: entitlement denied/required.
  • 409: idempotency conflict.
  • 422: invalid input or missing feature policy configuration.
  • 429: rate limit rejection.

For an entitlement 403, inspect the envelope code and meta. The server returns the rejected resource_type, feature_code, and feature_family_code, so logs can identify the exact denied resource without reconstructing it from request text.

Verify checklist​

  • Same idempotency key + same payload returns the same lease.
  • Changing payload under same idempotency key returns 409.
  • Denied entitlement never returns an active lease.
  • Quota/rate/funding hints match expected account state.