Account Management API
Account Management API
XSI organizes accounts as a tree: every account has a parent account (PID), a tenant (OID) and a lineage path (DNA). Management APIs can only act on the caller's own subtree. For concepts, see Account Hierarchy.
export XSI_BASE_URL="https://api.xsicontrol.com" # Or your own API domain
export XSI_API_KEY="sk-Xvs..." # Key of a manager accountEndpoints at a glance
| Method and path | Permission | Description |
|---|---|---|
POST /x-users | Manager with remaining sub-account quota | Create a direct sub-account |
GET /x-users, GET /x-users/{identifier} | Manager | List direct sub-accounts |
GET /x-dna, GET /x-dna/{identifier} | Manager | List all descendants |
PUT /x-users/{identifier} (or POST) | Manager; account holders can update part of their own profile | Update an account |
POST /x-users/batch-credit | Manager | Grant or claw back credit in bulk |
DELETE /x-users/{identifier} | Manager | Delete a descendant |
POST /x-self | Any account | Rotate your own API key |
POST /x-news, POST /x-news/{target} | root / manager | Publish a notification |
DELETE /x-news, DELETE /x-news/{target} | root / manager | Delete notifications |
Manager: root; or an account that meets all of: TPD > 800000000, sub-account capability (UserLimit > 0 or existing sub-accounts), and a balance above USER_API_BALANCE (default 100). Otherwise the API returns 403 with a body stating which requirement is missing, e.g. Management access requires balance above 100.00.. Use the manage field of GET /dashboard/status to check in advance.
Field names: request bodies use PascalCase field names (e.g. CreditGranted, AllowModels). The update endpoint returns 400 Unknown field: X for unknown fields; most known fields with the wrong casing or type are silently ignored (except CreditGranted and DryRun, which return 400), so write them exactly as shown on this page.
Create a sub-account
curl -X POST "$XSI_BASE_URL/x-users" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Email": "[email protected]",
"Name": "dev-a",
"Alias": "R&D A",
"CreditGranted": 200,
"RPM": 60,
"TPM": 200000
}'| Field | Required | Description |
|---|---|---|
Email | Yes | Login and notification email; globally unique, β€ 128 bytes |
Name | No | Account name; globally unique; 2β63 bytes of letters, digits, _ and -, with at least one letter. If omitted, c_ plus 10 random characters is generated |
Alias | No | Display name, same rules as Name; generated from the email if invalid |
BillingEmail | No | Billing email; multiple addresses allowed (separated by ,, ; or whitespace, total length β€ 256); defaults to Email |
CreditGranted | No | Initial credit (in the sub-account's pricing); at least USER_MIN_BALANCE (default 1). If omitted, that minimum is still granted |
Rates | No | Price multiplier; max(requested value, parent Rates) |
Factor | No | Price factor. If the parent is a tenant owner, max(requested value, parent Factor); otherwise equal to the parent's value |
RPM, RPH, RPD, TPM, TPH, TPD | No | Account-level rate limits; each is min(requested value, parent value). Inherited from the parent if omitted or less than 1 |
UserLimit | No | Number of sub-accounts this account may create; default 0. Forced to 0 if the parent is not root and its own UserLimit < 64 |
FundingType | No | Tenant owners only: subscription (subscription credit) or payg (pay-as-you-go credit) |
SecretKey | No | Key for the sub-account (must be a valid 51-character sk-Xvs key); generated automatically if omitted |
The following attributes are inherited from the parent and are ignored if passed at creation; adjust them afterwards with the update endpoint if needed: Level, Gear, Role, DailyLimit, Resources, AllowIPs, AllowModels, AllowLevels, ModelLimits, ModelMapper, LevelMapper. HardLimit and SoftLimit are calculated automatically from the initial balance.
Source of credit:
- If the caller is a tenant owner, credit is granted directly without reducing the caller's balance; it is valid for 1 year by default.
- If the caller is a regular manager, credit is transferred from the caller's balance: the caller is debited
CreditGranted Γ· child.Rates Γ parent.Rates, and the sub-account's credit keeps the expiry and funding type of the source credit. If the balance is insufficient, the API returns403 Insufficient balance.
Response (200):
{
"Action": "add",
"User": {
"ID": 123,
"SecretKey": "sk-Xvs...",
"Updates": {"Name": "dev-a", "Level": 1, "Rates": 1, "CreditBalance": [], "UserLimit": 0}
}
}SecretKey is returned only once, in the creation response, and is also sent to the sub-account's Email in a welcome email. Store it securely.
| Status | Body | Cause |
|---|---|---|
400 | Invalid email address | Invalid email |
400 | Name: 4-63 chars, at least 1 letters | Invalid account name (the actual minimum is 2 bytes) |
400 | Invalid funding type ... | Invalid FundingType value |
403 | Only owner can specify FundingType | A non-owner specified a funding type |
403 | Sub-user limit reached / Management access requires remaining sub-user quota. | Sub-account quota exhausted |
403 | Insufficient balance | Insufficient balance for the credit transfer |
409 | User already exists | Account name or email already in use |
Query accounts
GET /x-users # Direct sub-accounts
GET /x-dna # All descendants
GET /x-dna?level=2&page=1&size=50&order=desc
GET /x-users/42 # By ID
GET /x-dna/[email protected] # By email
GET /x-dna/.1.5. # By DNA prefix
GET /x-dna/L2 # All descendants on Level 2Query parameters (only for /x-users and /x-dna themselves):
| Parameter | Description |
|---|---|
id, name, email, level | Exact match |
dna | DNA prefix match |
page, size | Pagination; at most 8192 items per page |
order | desc (or id_desc) sorts by ID descending; anything else sorts ascending |
Path identifiers (/x-users/{identifier}, /x-dna/{identifier}): a number is an ID; a value containing @ is an email; a value starting with . is a DNA prefix; L<n>, G<n>, R<n>, T<n> and F<x> filter by Level, Gear, Role, Tier and Factor respectively; anything else is treated as an account name.
Response: always an array of account objects; [] when nothing matches. SecretKey, PublicKey, PartialKey and EncryptionKey are masked as "*". Response headers include X-Total-Count; paginated responses also include X-Page, X-Per-Page and X-Total-Pages.
Every call to GET /x-users or GET /x-dna is charged XAPI_FEE (default Β₯0.012).
Update an account
curl -X PUT "$XSI_BASE_URL/x-users/dev-a" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CreditGranted": 100,
"Days": 90,
"DailyLimit": 50,
"AllowModels": "gpt-6* claude-sonnet-5-5",
"AllowIPs": "203.0.113.0/24"
}'Targeting: /x-users/{identifier}, or /x-users?id=..., /x-users?name=.... Numeric IDs are looked up globally and then checked to be a descendant of the caller; account names and emails are looked up only among the caller's descendants. If the target is outside the subtree, the API returns 403 Forbidden (numeric ID) or 404 User not found.
Updatable fields
| Field | Who can set it | Description |
|---|---|---|
Email, Alias, BillingEmail, QRCode | Manager; the account itself | Profile |
InvoiceInfo | The account itself only | Invoice details {type, company_name, tax_no, registered_address, registered_phone, bank_name, bank_account, email} |
CreditGranted | Manager | Positive to top up, negative to claw back |
Days, DaysExplicit | Manager | Validity in days of newly added credit, see below |
Status | Manager (not on themselves) | false disables the account |
DailyLimit, HardLimit, SoftLimit | Manager | Daily limit and monthly limit (CNY); SoftLimit is only stored and takes no part in admission |
RPM, RPH, RPD, TPM, TPH, TPD | Manager | Account-level rate limits |
UserLimit | Manager | Sub-account quota |
Rates, Gear | Manager | Price multiplier (not lower than the caller's) and routing mode (not higher than the caller's) |
ModelLimits | Manager | Model-level limits |
Resources, AllowIPs, AllowModels, AllowLevels | Manager | Allowlists, see below |
ModelMapper | Manager | Account-level model mapping |
Scope, DryRun | Manager | Narrow descendants' allowlists in bulk, see below |
FundingType | Tenant owners only | Funding type of this credit change |
Level, Role, Factor, LevelMapper | Tenant owners only | Routing group, billing tier, price factor and account-level Level mapping |
When a non-owner updates their own account, only Email, Alias, BillingEmail, InvoiceInfo and QRCode can be changed.
Credit adjustments
- Tenant owners: positive amounts are granted directly (without debiting the owner's balance) and expire at
now + Days(default 365 days); negative amounts are deducted directly from the target and may take it below zero. - Regular managers: each update is charged one
XAPI_FEE. Positive amounts are transferred from the caller's balance (converted byRates); negative amounts return credit to the caller, capped at the target's balance, and incur anotherXAPI_FEE. HereDaysis only an upper bound: the new credit cannot expire later than the latest expiry of the caller's credit; withoutDays, the expiry of the source credit is kept. - When
|CreditGranted| > 0.5, a credit change email is sent to the target.
Allowlist syntax
The values of Resources, AllowIPs, AllowModels and AllowLevels are strings whose items are separated by commas, semicolons or whitespace:
| Syntax | Meaning |
|---|---|
a b c | Append these items (a bare list without prefixes appends and does not remove existing items) |
+x | Add an item |
-x | Remove an item |
* | Restore the parent account's scope |
-* | Clear. The combined form -*,+a,+b fully replaces the scope with a and b |
AllowIPssupports single IPs and CIDRs; loopback addresses are always allowed. AfterAllowLevelsis cleared, the account can still use its own Level.AllowModelssupports*wildcards, e.g.gpt-6*.Resourcesmatches by path prefix, e.g./v1/chat/completions,/v1/responses.- Scopes set by non-owners are intersected with the caller's own scope; invalid items are skipped.
Scope narrows an entire subtree at once: "Scope": "self" | "descendants" | "tree", supported only for Resources and AllowModels. Combine it with "DryRun": true to preview the impact first. On this path, invalid items cause an error.
ModelLimits
{"ModelLimits": {"gpt-6.2-sol": {"rpm": 30, "tpm": 400000}}}- Keys must be the exact upstream model name (the name after mapping); wildcards are not supported, and models not in the price table are ignored.
- Inner keys are lowercase
rpm,rph,rpd,tpm,tphandtpd. Dimensions not given in a new entry are unlimited; when updating an existing entry, dimensions not given keep their current values. - Limits apply only to Role 2 (strict) and Role 3 (subscription) accounts; see Access Control and Limits.
Response (200): {"Action": "update", "User": {"ID": 42, "Updates": {...}}}, where Updates is the full snapshot after the update. Every update writes an "Account Update" notification to the target, valid for 1 day.
Adjust credit in bulk
curl -X POST "$XSI_BASE_URL/x-users/batch-credit" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"CreditGranted": 50, "Filters": {"level": 2}, "Order": "asc", "DryRun": true}'| Field | Description |
|---|---|
CreditGranted | Required and non-zero: positive to grant, negative to claw back (in the sub-account's pricing) |
IDs | List of target IDs (β€ 8192). Passing [] matches no accounts |
Filters | id, name, email, dna (prefix), level, gear, role, tier, factor |
Order | desc sorts by ID descending; anything else sorts ascending |
Days, DaysExplicit | Same as the update endpoint |
FundingType | Tenant owners only |
DryRun | When true, calculate only without writing |
- The target set is the intersection of all of the caller's descendants with
IDsandFilters. If neitherIDsnorFiltersis given, all descendants are matched (at most 8192; more returns400 Too many target users), so always preview withDryRunfirst. - Clawbacks are applied only in full; accounts with insufficient balance are skipped.
- Once a regular manager runs out of balance on one account, all subsequent grants are skipped, so the result depends on
Order. - Regular managers are charged
XAPI_FEEonly once per batch.
Response:
{
"Action": "batch_credit", "DryRun": false, "CreditGranted": 50,
"RequestedCount": 3, "AppliedCount": 2, "SkippedCount": 1,
"TotalChildDelta": 100, "TotalParentDelta": -100.012,
"ParentBalanceBefore": 1000, "ParentBalanceAfter": 899.988, "ApiFee": 0.012,
"Results": [{"ID": 7, "Name": "dev-a", "Status": "applied", "CreditGranted": 50, "ParentDelta": -50, "Balance": 150}]
}Status values: applied, skipped_not_found, skipped_forbidden, skipped_parent_insufficient, skipped_invalid_rate, skipped_level_mismatch, skipped_parent_gear, skipped_child_insufficient, skipped_invalid_credit_state.
Delete an account
curl -X DELETE "$XSI_BASE_URL/x-users/dev-a" -H "Authorization: Bearer $XSI_API_KEY"- root can delete any account; other managers can delete only their own descendants.
- Deletion is a hard delete and does not cascade: sub-accounts of the deleted account remain in the original subtree and can still be managed by higher-level ancestors.
- The deleted account's positive balance is converted by
Ratesand refunded to the caller, any debt is deducted from the caller, and oneXAPI_FEEis charged. The positive balance is not refunded if the target'sTPD β€ 800000000, or if the caller is not a tenant owner and the Levels differ. - A notification email is sent to the deleted account.
Response: {"Action": "delete", "User": {"ID": 42, "Name": "dev-a", "Email": "...", "Rates": 1, "CreditBalance": [...]}}.
Rotate your own key
curl -X POST "$XSI_BASE_URL/x-self" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"confirm\": \"$(date +%F)-ROTATE-SELF\"}"| Field | Description |
|---|---|
confirm | Required confirmation phrase: <server local date YYYY-MM-DD>-ROTATE-SELF; ...-ROTATE-ROOT for the root account |
key | Optional; a new 51-character sk-Xvs key to use. Generated automatically if omitted |
- The old key is invalidated immediately; the new key is returned in the response and sent to your
EmailandBillingEmail. - After a successful rotation, you cannot rotate again for 10 minutes:
429 API Key was regenerated recently. Please try again later.(withRetry-After: 600).
{"success": true, "message": "Self key rotated successfully",
"rotate": {"action": "rotate_self", "id": 42, "name": "dev-a", "email": "...", "key": "sk-Xvs...", "timestamp": "..."}}Notifications and announcements
curl -X POST "$XSI_BASE_URL/x-news/dev-a" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Maintenance notice", "content": "Upstreams will be switched tonight at 23:00.", "days": 3}'| Path | Recipients | Permission |
|---|---|---|
/x-news | All accounts (system announcement) | root only |
/x-news/{ID, account name or email} | A specific account | Target must be a descendant of the caller |
/x-news/.{DNA} | Accounts whose DNA exactly equals this value (i.e. direct sub-accounts of the same parent) | The DNA must contain the caller |
- Request body:
title(optional),content(required),days(1β32; out-of-range values become 32). - At most the 8 most recent notifications are kept per recipient.
DELETEon the same path deletes all notifications for that recipient.- Accounts read notifications with
GET /dashboard/news; personal notifications are cleared after being read once.