Authorize

Scope

This page defines authorize-time admission behavior and lease issuance rules.

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.

Decision sequence

1. Enforce seat constraints (when seat features are configured).
2. Resolve feature and feature family.
3. Enforce entitlement for the feature/family.
4. Resolve active policy windows for the current bundle.
5. Evaluate quota/rate admission.
6. Evaluate budget/funding feasibility in prepaid mode.
7. Issue lease and return lease token + 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.
• 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 and seat id
  • 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 caller provides budget_id, authorize evaluates current budget headroom snapshot.
• In prepaid mode, insufficient grant coverage or budget coverage is surfaced via hints and may block with 402 depending on condition.
• Funding and budget hints are muted in non-prepaid billing modes.

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.

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 token.
• Quota/rate/funding hints match expected account state.