Users users
Admins manage platform accounts: create, view, update, enable/disable, reset passwords, turn off TOTP. An account must be disabled before it can be deleted.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/usersList users
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
ids | string | Only list these IDs: comma-separated positive integers, at most 200 after deduplication (same as the page_size limit; more, or a malformed value, returns 422); an empty value is the same as omitting it. Combined with other filters as an intersection; IDs you cannot see are silently left out. Pagination is unchanged: set page_size to at least the number of IDs to get them in one page |
email | string | |
phone | string | Phone number |
username | string | Username |
/api/v2/usersCreate user
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
currency | CurrencyBrief | Account currency (ISO 4217) and symbol; balance, recharges and orders use it, and the panel formats amounts with it; the new-user default when there is no account yet |
email | string | |
enabled | boolean | Whether enabled |
login_ip_allow | string[] | Login IP allowlist (IPs or CIDRs); empty means no restriction |
login_verify | LoginVerify | Second-factor login: none means not required; email / sms also require an email/SMS code at login (the platform must allow it and the address must be bound) |
password | string | Required on create; on update, providing it resets the password and revokes all sessions and deletes all API keys of the user (audit detail records api_keys_revoked) |
phone | string | Phone number |
role | string | Account role: admin or tenant |
totp_enabled | boolean | Whether TOTP is enabled |
usernameRequired | string | Username |
/api/v2/users/batchBatch enable, disable or delete users
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
actionRequired | string | enable, disable or delete. |
idsRequired | integer[] | User IDs to operate on, 1 to 100 per call. |
/api/v2/users/{id}Get user
Authentication: Admin only
/api/v2/users/{id}Update user
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
currency | CurrencyBrief | Account currency (ISO 4217) and symbol; balance, recharges and orders use it, and the panel formats amounts with it; the new-user default when there is no account yet |
email | string | |
enabled | boolean | Whether enabled |
login_ip_allow | string[] | Login IP allowlist (IPs or CIDRs); empty means no restriction |
login_verify | LoginVerify | Second-factor login: none means not required; email / sms also require an email/SMS code at login (the platform must allow it and the address must be bound) |
password | string | Required on create; on update, providing it resets the password and revokes all sessions and deletes all API keys of the user (audit detail records api_keys_revoked) |
phone | string | Phone number |
role | string | Account role: admin or tenant |
totp_enabled | boolean | Whether TOTP is enabled |
usernameRequired | string | Username |
/api/v2/users/{id}Delete user
Authentication: Admin only
/api/v2/users/{user_id}/accountGet user account
Authentication: Admin only
/api/v2/users/{user_id}/accountFreeze or unfreeze user account
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
freeze_reason | string | Freeze reason; empty if not frozen. |
frozenRequired | boolean | Whether the account is frozen; deductions are rejected while frozen. |
/api/v2/users/{user_id}/api-keysList a user's API keys
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
/api/v2/users/{user_id}/api-keysCreate an API key for a user
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
expires_at | string | Expires at |
nameRequired | string | Name |
password | string | Required on create; on update, providing it resets the password and revokes all sessions and deletes all API keys of the user (audit detail records api_keys_revoked) |
scopesRequired | string[] | Granted scopes, same values as scopes at creation |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
/api/v2/users/{user_id}/api-keys/{id}Update a user's API key IP allowlist or reset it
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
password | string | Required on create; on update, providing it resets the password and revokes all sessions and deletes all API keys of the user (audit detail records api_keys_revoked) |
reset | boolean | When true, issue a new key; the old one stops working at once |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
/api/v2/users/{user_id}/api-keys/{id}Delete a user's API key
Authentication: Admin only
/api/v2/users/{user_id}/rechargesRecharge or deduct user balance
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
amount_centsRequired | integer | Amount in cents; must be a positive integer. |
currency | CurrencyBrief | Account currency (ISO 4217) and symbol; balance, recharges and orders use it, and the panel formats amounts with it; the new-user default when there is no account yet |
direction | string | credit = recharge (default), debit = deduct. |
remark | string | Remark |
Users object
| Field | Type | Description |
|---|---|---|
actionRequired | string | enable, disable or delete. |
active_packages | integer | Number of active packages (end_at in the future; one of the blockers for changing the account currency). Only the admin GET /users/{user_id}/account returns it. |
affected | integer | Number of users processed. |
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
amount_centsRequired | integer | Amount in cents; must be a positive integer. |
archived | boolean | Moved into the archive table by the archiving task (read-only). |
avatar_ver | integer | Avatar version, increases on every upload; empty when there is no avatar |
balance_cents | integer | Account balance in cents, same as balance_cents of GET /users/{user_id}/account (0 when there is no account). Only present in the GET /users list, not in single-user responses |
certified | boolean | Whether real-name verification has passed |
client_ip | string | Source IP of this request, derived the same way as the login IP allowlist check (what the allowlist compares is what is shown). Only present in GET /me and PUT /me |
created_at | string | Created at |
currencies | AccountCurrencyOption[] | Selectable enabled currencies (base first, then by code); only present when currency_changeable is true, only in GET /account and the admin GET /users/{user_id}/account. |
currency | CurrencyBrief | Account currency (ISO 4217) and symbol; balance, recharges and orders use it, and the panel formats amounts with it; the new-user default when there is no account yet |
currency_changeable | boolean | Whether the tenant can change the account currency now (zero balance, no unpaid orders, no active packages). Only GET /account and the admin GET /users/{user_id}/account return it. |
data | object | Extra data (such as package purchase details); a top-up paying a shortfall carries intent (state pending/running/done/failed; code/reason explain a failure; user_package_id is the package fulfilled when done). |
default_currency | string | Default account currency for new users (ISO 4217); lets the tenant UI tell whether the account currency was never changed (only then is it preselected by UI language). Sent together with currencies, only when currency_changeable is true, only in GET /account and the admin GET /users/{user_id}/account. |
delegated_session | boolean | Whether the current session was issued by superadmin sign-in or switch-to-user (if so, password, email, phone, login allowlist, login verification and real-name are read-only). Only present in GET /me and PUT /me |
des | string | Description |
direction | string | credit = recharge (default), debit = deduct. |
email | string | |
enabled | boolean | Whether enabled |
expires_at | string | Expires at |
freeze_reason | string | Freeze reason; empty if not frozen. |
frozen | boolean | Whether the account is frozen; deductions are rejected while frozen. |
id | integer | Record ID |
idsRequired | integer[] | User IDs to operate on, 1 to 100 per call. |
ip_site_new | boolean | The user has an in-use (not expired) package that opens IP sites, so they can create IP sites, pick new IPs, issue paid ZeroSSL (zerossl_api) certificates and set API keys on ZeroSSL accounts. Only present in GET /me; always true for admins |
ip_site_on | boolean | ip_site_new is true, or the user already owns an IP site, an IP certificate (all SANs are IPs) or a ZeroSSL account with an API key (free ZeroSSL accounts do not count), so IP site menus and tabs are shown and existing data can be viewed, edited and deleted. Only present in GET /me; always true for admins |
last_used_at | string | Time of last use; null if never used |
ledger_id | integer | ID of the linked ledger entry; null if none. |
login_ip_allow | string[] | Login IP allowlist (IPs or CIDRs); empty means no restriction |
login_verify | LoginVerify | Second-factor login: none means not required; email / sms also require an email/SMS code at login (the platform must allow it and the address must be bound) |
mch_order_no | string | Merchant order number (the gateway-side order number); null for non-online payments. |
name | string | Name |
nickname | string | Nickname; empty when not set (the UI shows the username) |
paid_at | string | Payment time; null if unpaid. |
password | string | Required on create; on update, providing it resets the password and revokes all sessions and deletes all API keys of the user (audit detail records api_keys_revoked) |
pay_type | string | admin/balance/alipay/wxpay, etc.; empty = unpaid. |
phone | string | Phone number |
prefix | string | First few characters of the plaintext key, for recognition |
rate_to_base | string | Rate at order time: 1 unit of this currency = ? base currency (decimal string, 8 places); later rate changes do not affect it. |
remark | string | Remark |
reset | boolean | When true, issue a new key; the old one stops working at once |
role | string | Account role: admin or tenant |
scopes | string[] | Granted scopes, same values as scopes at creation |
secret | string | Plaintext key (the X-API-Key value), returned only once at creation; only a hash is stored |
status | string | Order status: unpaid or paid. |
tenant_id | integer | Owner tenant (user) ID |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
totp_enabled | boolean | Whether TOTP is enabled |
totp_recovery_left | integer | Number of unused TOTP recovery codes. Only present in GET /me and PUT /me when TOTP is enabled |
transaction_id | string | Gateway-side transaction ID; empty if unpaid. |
type | string | recharge (admin recharge) / deduct (admin deduction) / payment (online payment) / package (package purchase), etc. |
unpaid_orders | integer | Number of unpaid orders (one of the blockers for changing the account currency). Only the admin GET /users/{user_id}/account returns it. |
updated_at | string | Updated at |
user_id | integer | User ID |
username | string | Username |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}