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 account

Endpoints at a glance

Method and pathPermissionDescription
POST /x-usersManager with remaining sub-account quotaCreate a direct sub-account
GET /x-users, GET /x-users/{identifier}ManagerList direct sub-accounts
GET /x-dna, GET /x-dna/{identifier}ManagerList all descendants
PUT /x-users/{identifier} (or POST)Manager; account holders can update part of their own profileUpdate an account
POST /x-users/batch-creditManagerGrant or claw back credit in bulk
DELETE /x-users/{identifier}ManagerDelete a descendant
POST /x-selfAny accountRotate your own API key
POST /x-news, POST /x-news/{target}root / managerPublish a notification
DELETE /x-news, DELETE /x-news/{target}root / managerDelete 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
  }'
FieldRequiredDescription
EmailYesLogin and notification email; globally unique, ≀ 128 bytes
NameNoAccount name; globally unique; 2–63 bytes of letters, digits, _ and -, with at least one letter. If omitted, c_ plus 10 random characters is generated
AliasNoDisplay name, same rules as Name; generated from the email if invalid
BillingEmailNoBilling email; multiple addresses allowed (separated by ,, ; or whitespace, total length ≀ 256); defaults to Email
CreditGrantedNoInitial credit (in the sub-account's pricing); at least USER_MIN_BALANCE (default 1). If omitted, that minimum is still granted
RatesNoPrice multiplier; max(requested value, parent Rates)
FactorNoPrice 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, TPDNoAccount-level rate limits; each is min(requested value, parent value). Inherited from the parent if omitted or less than 1
UserLimitNoNumber of sub-accounts this account may create; default 0. Forced to 0 if the parent is not root and its own UserLimit < 64
FundingTypeNoTenant owners only: subscription (subscription credit) or payg (pay-as-you-go credit)
SecretKeyNoKey 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 returns 403 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.

StatusBodyCause
400Invalid email addressInvalid email
400Name: 4-63 chars, at least 1 lettersInvalid account name (the actual minimum is 2 bytes)
400Invalid funding type ...Invalid FundingType value
403Only owner can specify FundingTypeA non-owner specified a funding type
403Sub-user limit reached / Management access requires remaining sub-user quota.Sub-account quota exhausted
403Insufficient balanceInsufficient balance for the credit transfer
409User already existsAccount 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 2

Query parameters (only for /x-users and /x-dna themselves):

ParameterDescription
id, name, email, levelExact match
dnaDNA prefix match
page, sizePagination; at most 8192 items per page
orderdesc (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

FieldWho can set itDescription
Email, Alias, BillingEmail, QRCodeManager; the account itselfProfile
InvoiceInfoThe account itself onlyInvoice details {type, company_name, tax_no, registered_address, registered_phone, bank_name, bank_account, email}
CreditGrantedManagerPositive to top up, negative to claw back
Days, DaysExplicitManagerValidity in days of newly added credit, see below
StatusManager (not on themselves)false disables the account
DailyLimit, HardLimit, SoftLimitManagerDaily limit and monthly limit (CNY); SoftLimit is only stored and takes no part in admission
RPM, RPH, RPD, TPM, TPH, TPDManagerAccount-level rate limits
UserLimitManagerSub-account quota
Rates, GearManagerPrice multiplier (not lower than the caller's) and routing mode (not higher than the caller's)
ModelLimitsManagerModel-level limits
Resources, AllowIPs, AllowModels, AllowLevelsManagerAllowlists, see below
ModelMapperManagerAccount-level model mapping
Scope, DryRunManagerNarrow descendants' allowlists in bulk, see below
FundingTypeTenant owners onlyFunding type of this credit change
Level, Role, Factor, LevelMapperTenant owners onlyRouting 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 by Rates); negative amounts return credit to the caller, capped at the target's balance, and incur another XAPI_FEE. Here Days is only an upper bound: the new credit cannot expire later than the latest expiry of the caller's credit; without Days, the expiry of the source credit is kept.
  • When |CreditGranted| > 0.5, a credit change email is sent to the target.
Updates by regular managers realign the plan: any regular update by a regular manager (not a tenant owner) to a descendant, even one that only changes profile fields, aligns the target's Level, Role, model mapping, Level mapping and support QR code with the manager's own values; if the target's Level differs from the manager's, the target's positive balance is cleared first, and cross-Level deductions are rejected. Check the target's plan settings first to avoid mistakes.

Allowlist syntax

The values of Resources, AllowIPs, AllowModels and AllowLevels are strings whose items are separated by commas, semicolons or whitespace:

SyntaxMeaning
a b cAppend these items (a bare list without prefixes appends and does not remove existing items)
+xAdd an item
-xRemove an item
*Restore the parent account's scope
-*Clear. The combined form -*,+a,+b fully replaces the scope with a and b
  • AllowIPs supports single IPs and CIDRs; loopback addresses are always allowed. After AllowLevels is cleared, the account can still use its own Level.
  • AllowModels supports * wildcards, e.g. gpt-6*.
  • Resources matches 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, tph and tpd. 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}'
FieldDescription
CreditGrantedRequired and non-zero: positive to grant, negative to claw back (in the sub-account's pricing)
IDsList of target IDs (≀ 8192). Passing [] matches no accounts
Filtersid, name, email, dna (prefix), level, gear, role, tier, factor
Orderdesc sorts by ID descending; anything else sorts ascending
Days, DaysExplicitSame as the update endpoint
FundingTypeTenant owners only
DryRunWhen true, calculate only without writing
  • The target set is the intersection of all of the caller's descendants with IDs and Filters. If neither IDs nor Filters is given, all descendants are matched (at most 8192; more returns 400 Too many target users), so always preview with DryRun first.
  • 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_FEE only 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 Rates and refunded to the caller, any debt is deducted from the caller, and one XAPI_FEE is charged. The positive balance is not refunded if the target's TPD ≀ 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\"}"
FieldDescription
confirmRequired confirmation phrase: <server local date YYYY-MM-DD>-ROTATE-SELF; ...-ROTATE-ROOT for the root account
keyOptional; 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 Email and BillingEmail.
  • After a successful rotation, you cannot rotate again for 10 minutes: 429 API Key was regenerated recently. Please try again later. (with Retry-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}'
PathRecipientsPermission
/x-newsAll accounts (system announcement)root only
/x-news/{ID, account name or email}A specific accountTarget 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.
  • DELETE on the same path deletes all notifications for that recipient.
  • Accounts read notifications with GET /dashboard/news; personal notifications are cleared after being read once.