Access Control and Limits

XSI runs every request through an admission pipeline in a fixed order. All rules are configured on accounts and narrow down the account tree.

Admission order

OrderCheckOn failure
1API key format and validity401
2IP allowlist AllowIPs403
3Account status Status403
4Frozen state (balance below threshold)429 (401 on the request that triggers the freeze)
5Daily quota DailyLimit, monthly quota HardLimit429
6Account-level rate limits RPM … TPD429
7Resource allowlist Resources403
8Model allowlist AllowModels403
9Model-level limits ModelLimits / MODEL_LIMITS429
  • Checks 5, 6, and 9 depend on the billing tier (Role); see below.
  • GET /dashboard/* (including /dashboard/models) and /user/balance are exempt from the resource allowlist, freezes, and quotas, so account status can always be viewed; GET /v1/models is exempt only from the resource allowlist.
  • The model allowlist and model limits only block POST requests.
  • Setting USER_FILTER=false at deployment skips checks 2–9 and XAPI_FEE for the regular HTTP proxy (usage-based billing still runs as usual); Responses WebSocket, Live, and Realtime WebRTC still run their own admission checks. Use it only in fully trusted internal environments.

Billing tier (Role)

RoleNameDaily/monthly quota, account-level rate limits, model limits
0, 1UnlimitedNot checked
2StrictAll checked
3SubscriptionChecked while subscription credit is in use; when subscription credit runs out or a limit is hit and the account has a pay-as-you-go balance, the request is allowed and billed to that balance
Otherβ€”Treated as strict

root, created by INIT_USERS, is Role 0; in single-tenant mode self-registered accounts inherit root's current Role (usually 0), and in multi-tenant mode they default to Role 1; sub-accounts inherit their parent's Role. For quotas and rate limits to take effect on an account, the tenant owner must set its Role to 2 or 3. Balance checks and freezes apply to every Role.

Allowlists

FieldMatchingExample
AllowIPsExact IP or CIDR203.0.113.10 10.0.0.0/8
ResourcesExact or prefix path match/v1/chat/completions /v1/responses
AllowModelsExact or * wildcard; checked against the requested model, the mapped model, and the billed modelgpt-6* claude-sonnet-5-5
AllowLevelsLevel numbers, used for cross-group retries by Gear ≀ 0 accounts1 3
  • Empty means unrestricted. On update, a list without prefixes appends; to replace fully, write -*,+a,+b.
  • The update syntax supports +x to add, -x to remove, and * to reset to the parent's scope; see Account management API.
  • When the resource allowlist rejects a POST or WebSocket request, or the model allowlist rejects a POST request, a one-time XAPI_FEE is charged.

Quotas

FieldMeaning
DailyLimitDaily spending cap (CNY), resets the next day
HardLimitMonthly spending cap (CNY), resets the next month
SoftLimitMonthly reference value that can be stored and queried; the current version neither rejects requests nor sends notifications based on it
USER_MIN_BALANCEFreeze threshold (deployment-level). The account is frozen when its balance falls below this value minus 0.01 and recovers after a top-up

The balance is checked every 10 requests and after every charge, so it can be briefly overdrawn into negative territory; the debt is offset by the next top-up.

Rate limits

Account level: RPM, RPH, RPD, TPM, TPH, TPD.

Model level: {"<upstream model name>": {"rpm", "rph", "rpd", "tpm", "tph", "tpd"}}. The account's ModelLimits takes precedence, then the tenant's MODEL_LIMITS; matching is exact against the mapped upstream model name, with no wildcards.

DimensionWindowRecovers
RPM / TPM1 minuteAfter 1 minute
RPH / TPH1 hourAfter 1 hour
RPD / TPDCalendar dayAt midnight the next day
  • Requests are counted on entry; tokens are added after the request completes, so token limits decide whether the next request gets in.
  • In model limits, an explicitly given cap for a longer window also caps the shorter windows; for the six account-level values, fill in mutually consistent values.
  • 999999999999999999 means unlimited.
  • Realtime endpoints: a new Realtime WebSocket is checked once (attaching to an existing call via call_id is not checked again); Responses WebSocket is checked once per turn; the Live main WebSocket is checked at the first frame; creating a Live WebRTC session may currently consume two requests of quota.

Authentication protection

  • 12 authentication failures from the same IP within 1 minute trigger a 2-minute ban; 48 failures within 10 minutes trigger a 15-minute ban.
  • The same invalid key is rejected outright for 90 seconds without a database lookup.
  • The client IP is read from forwarding headers only when the request comes from a proxy within TRUSTED_PROXY_CIDRS; see Reverse proxy.

Best practices

  • Split accounts by purpose: use separate sub-accounts and keys for production, testing, and personal development.
  • Set AllowIPs on production accounts, and AllowModels and Resources on accounts distributed externally.
  • Use Role 2 for accounts that need budget control, and set both DailyLimit and HardLimit.
  • Set model-level tpm or rpd on expensive models so a single account cannot exhaust the upstream quota.