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
| Order | Check | On failure |
|---|---|---|
| 1 | API key format and validity | 401 |
| 2 | IP allowlist AllowIPs | 403 |
| 3 | Account status Status | 403 |
| 4 | Frozen state (balance below threshold) | 429 (401 on the request that triggers the freeze) |
| 5 | Daily quota DailyLimit, monthly quota HardLimit | 429 |
| 6 | Account-level rate limits RPM β¦ TPD | 429 |
| 7 | Resource allowlist Resources | 403 |
| 8 | Model allowlist AllowModels | 403 |
| 9 | Model-level limits ModelLimits / MODEL_LIMITS | 429 |
- Checks 5, 6, and 9 depend on the billing tier (Role); see below.
- GET
/dashboard/*(including/dashboard/models) and/user/balanceare exempt from the resource allowlist, freezes, and quotas, so account status can always be viewed; GET/v1/modelsis exempt only from the resource allowlist. - The model allowlist and model limits only block POST requests.
- Setting
USER_FILTER=falseat deployment skips checks 2β9 andXAPI_FEEfor 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)
| Role | Name | Daily/monthly quota, account-level rate limits, model limits |
|---|---|---|
0, 1 | Unlimited | Not checked |
2 | Strict | All checked |
3 | Subscription | Checked 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
| Field | Matching | Example |
|---|---|---|
AllowIPs | Exact IP or CIDR | 203.0.113.10 10.0.0.0/8 |
Resources | Exact or prefix path match | /v1/chat/completions /v1/responses |
AllowModels | Exact or * wildcard; checked against the requested model, the mapped model, and the billed model | gpt-6* claude-sonnet-5-5 |
AllowLevels | Level numbers, used for cross-group retries by Gear β€ 0 accounts | 1 3 |
- Empty means unrestricted. On update, a list without prefixes appends; to replace fully, write
-*,+a,+b. - The update syntax supports
+xto add,-xto 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_FEEis charged.
Quotas
| Field | Meaning |
|---|---|
DailyLimit | Daily spending cap (CNY), resets the next day |
HardLimit | Monthly spending cap (CNY), resets the next month |
SoftLimit | Monthly reference value that can be stored and queried; the current version neither rejects requests nor sends notifications based on it |
USER_MIN_BALANCE | Freeze 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.
| Dimension | Window | Recovers |
|---|---|---|
| RPM / TPM | 1 minute | After 1 minute |
| RPH / TPH | 1 hour | After 1 hour |
| RPD / TPD | Calendar day | At 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.
999999999999999999means unlimited.- Realtime endpoints: a new Realtime WebSocket is checked once (attaching to an existing call via
call_idis 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
AllowIPson production accounts, andAllowModelsandResourceson accounts distributed externally. - Use Role 2 for accounts that need budget control, and set both
DailyLimitandHardLimit. - Set model-level
tpmorrpdon expensive models so a single account cannot exhaust the upstream quota.