Admin
System-level AI maintenance. Day-to-day billing administration (usage profiles, budgets, subscriptions) lives in Usage & Credits and Subscriptions.
POST /api/_ai-refresh-cache
Force an immediate License Manager sync, refreshing the local entitlement cache. Normally the cache refreshes on a schedule; use this to pick up changes right away or to recover after a sync failure.
Authentication: Required (session)
Pre-blocks: permission.ai.manage
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
progress | string | No | Optional progress channel id for streaming sync progress |
Response:
{
"success": true,
"syncedAt": "2026-05-23T14:45:00Z",
"creditBalance": { "included": 50000, "used": 12340, "remaining": 37660 }
}
What the sync refreshes
A refresh pulls the latest state from the License Manager into AiEntitlementCache:
- Entitlement JWT — the signed token that gates AI access and carries provider API keys
- Credit pool balance —
included/used/remainingcredits - Resource-type rate card — credit rates used for local metering
- Models — the available model list
- Subscription & billing config — current subscription and auto-replenish/alert settings
It also drains any unreported usage events to the License Manager as part of the sync.
Sync health
License Manager connectivity is surfaced on the usage summary so the UI can warn when the license server is unreachable. See the sync block of GET /api/usage:
| Field | Meaning |
|---|---|
syncedAt | Timestamp of the last successful sync |
lastSyncFailedAt | null when the most recent attempt succeeded; set when it failed |
lastSyncFailureCode | One of lm_unreachable, lm_unavailable, lm_error, license_not_recognized |
If users cannot use AI features, confirm AI is enabled for the tenant, run a refresh to re-sync the entitlement JWT, and check the credit pool balance via GET /api/usage. A 402 Payment Required with a code indicates which limit was hit — see the enforcement flow.