Account Hierarchy
XSI models multi-tenancy and multi-level resale as a single account tree: the platform, tenants, teams, members, and customers are all accounts in the tree. Each level can allocate credit, models, and permissions to the level below, within the bounds granted from above.
Roles
| Role | Condition | Capabilities |
|---|---|---|
| root | DNA == ".", created from the account named root in INIT_USERS | Platform super administrator: system announcements, signup domain policy, management of all accounts |
| Tenant owner | ID == OID | Owns a dedicated upstream key pool, tenant configuration, and pricing; can issue credit directly |
| Manager | Any account that meets the manager criteria | Creates, updates, and deletes its own descendants and views their usage |
| Regular account | Everyone else | Calls models, views its own usage, rotates its own key |
Manager criteria: TPD > 800000000, sub-account capability (UserLimit > 0 or existing sub-accounts), and a balance above USER_API_BALANCE (default 100), all at once. root is exempt.
Tenants
| Deployment mode | Tenant structure |
|---|---|
Single-tenant (SINGLE_TENANT=true, default) | Self-registered accounts join the root tenant and share root's key pool and configuration. Suited to internal enterprise or single-brand API services. Accounts in INIT_USERS other than root each become an independent tenant; for all accounts to share root's key pool, initialize only root and create accounts under it |
Multi-tenant (SINGLE_TENANT=false) | Every self-registered user becomes an independent tenant with its own key pool (BYOK), configuration, pricing, and account tree. Suited to cloud services for teams or service providers |
Tenants are fully isolated: keys, configuration, and pricing are isolated by OID, and account management is isolated by DNA subtree.
Account identifiers
| Field | Description |
|---|---|
ID | Account ID |
PID | ID of the direct parent account |
OID | ID of the owning tenant owner |
DNA | Path of ancestor IDs (excluding the account itself) |
Name / Email | Globally unique account name and email |
SecretKey | API key, a 51-character string starting with sk-Xvs; the plaintext is returned only on creation or rotation |
PublicKey | Public identifier pk-Xvs..., used for referral signups |
DNA
root's DNA is .; a sub-account's DNA is parent DNA + parent ID + ".".
root (ID 1) DNA = .
ββ team-a (ID 5) DNA = .1.
ββ dev-a (ID 9) DNA = .1.5.
ββ bot (ID 12) DNA = .1.5.9.- A is an ancestor of B if and only if B's DNA contains
.A.ID.. - All descendants of account X are the accounts whose DNA starts with
X.DNA + X.ID + ".". - Query endpoints can filter an entire branch by DNA prefix, for example
GET /x-dna/.1.5..
Inheritance and narrowing
When a sub-account is created, it inherits the following attributes from its parent: Level, Gear, Role, daily quota, resource allowlist, IP allowlist, model allowlist, Level allowlist, model limits, model mappings, and Level mappings.
Later changes by regular managers follow the rule "narrow only, never widen" (tenant owners can set descendants' prices, routing gears, and rate limits independently within the system caps):
| Attribute | Rule |
|---|---|
Rates | Not lower than the parent |
Factor | Not lower than the parent if the parent is a tenant owner; otherwise equal to the parent |
RPM β¦ TPD | Not higher than the parent (bounded by the operator) |
Resources, AllowModels, AllowIPs | Intersected with the operator's scope |
UserLimit | Not higher than the parent; 0 for the sub-account if the parent is not root and its own UserLimit < 64 |
Level, Role, Factor, LevelMapper | Only a tenant owner can change them |
A manager can manage descendants at any depth, with clamping based on the operator's own bounds.
Credit flow
| Operation | Tenant owner | Regular manager |
|---|---|---|
| Grant credit to a sub-account | Issued directly, without deducting the owner's balance | Transferred from the manager's own balance, converted at child.Rates Γ· parent.Rates, keeping the original credit's expiry and fund type |
| Claw back credit | Deducted directly from the target | Returned to the manager's own balance; each update is charged one XAPI_FEE, and a clawback is charged one more |
| Delete a sub-account | If the target's TPD > 800000000, the remaining positive balance is converted and refunded to the operator, otherwise it is forfeited; any debt is absorbed by the operator | Same, and the Levels must also match for a refund |
Deleting an account is a hard, non-cascading delete: the deleted account's sub-accounts stay in the original branch and continue to be managed by the ancestors above.
Plan following
For an account whose parent is not a tenant owner, Level and pricing follow the parent (plan_follows_parent is true in GET /dashboard/status). When a regular manager updates a sub-account whose Level differs from its own, the sub-account's positive balance is cleared first and its Level is then aligned with the manager's.
Typical structures
Internal enterprise
root
ββ R&D (manager, Level 1, monthly quota Β₯20,000)
β ββ Frontend team
β ββ Backend team
ββ Customer support (AllowModels: gpt-6-luna claude-haiku-5-5)API resale
root
ββ Channel A (Rates 1.0)
β ββ Customer A1 (Rates 1.2, margin goes to Channel A)
ββ Channel B (Rates 1.1, Factor 0.9)