Version 2.4.7.20261116085428 · latest

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.

User accountsAuthentication: Admin only13 endpoints

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.

GET/api/v2/usersList users

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
idsstring 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
emailstring Email
phonestring Phone number
usernamestring Username
POST/api/v2/usersCreate user

Authentication: Admin only

Request body application/json

FieldTypeDescription
currencyCurrencyBrief 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
emailstring Email
enabledboolean Whether enabled
login_ip_allowstring[] Login IP allowlist (IPs or CIDRs); empty means no restriction
login_verifyLoginVerify 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)
Values ["none","email","sms"]
passwordstring 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)
phonestring Phone number
rolestring Account role: admin or tenant
Values ["admin","tenant"]
totp_enabledboolean Whether TOTP is enabled
usernameRequiredstring Username
POST/api/v2/users/batchBatch enable, disable or delete users

Authentication: Admin only

Request body application/json

FieldTypeDescription
actionRequiredstring enable, disable or delete.
Values ["enable","disable","delete"]
idsRequiredinteger[] User IDs to operate on, 1 to 100 per call.
GET/api/v2/users/{id}Get user

Authentication: Admin only

PUT/api/v2/users/{id}Update user

Authentication: Admin only

Request body application/json

FieldTypeDescription
currencyCurrencyBrief 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
emailstring Email
enabledboolean Whether enabled
login_ip_allowstring[] Login IP allowlist (IPs or CIDRs); empty means no restriction
login_verifyLoginVerify 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)
Values ["none","email","sms"]
passwordstring 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)
phonestring Phone number
rolestring Account role: admin or tenant
Values ["admin","tenant"]
totp_enabledboolean Whether TOTP is enabled
usernameRequiredstring Username
DELETE/api/v2/users/{id}Delete user

Authentication: Admin only

PUT/api/v2/users/{user_id}/accountFreeze or unfreeze user account

Authentication: Admin only

Request body application/json

FieldTypeDescription
freeze_reasonstring Freeze reason; empty if not frozen.
frozenRequiredboolean Whether the account is frozen; deductions are rejected while frozen.
GET/api/v2/users/{user_id}/api-keysList a user's API keys

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
POST/api/v2/users/{user_id}/api-keysCreate an API key for a user

Authentication: Admin only

Request body application/json

FieldTypeDescription
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
expires_atstring Expires at
nameRequiredstring Name
passwordstring 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)
scopesRequiredstring[] Granted scopes, same values as scopes at creation
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.
PUT/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

FieldTypeDescription
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
passwordstring 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)
resetboolean When true, issue a new key; the old one stops working at once
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.
POST/api/v2/users/{user_id}/rechargesRecharge or deduct user balance

Authentication: Admin only

Request body application/json

FieldTypeDescription
amount_centsRequiredinteger Amount in cents; must be a positive integer.
currencyCurrencyBrief 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
directionstring credit = recharge (default), debit = deduct.
Values ["credit","debit"]Default "credit"
remarkstring Remark

Users object

FieldTypeDescription
actionRequiredstring enable, disable or delete.
Values ["enable","disable","delete"]
active_packagesinteger 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.
affectedinteger Number of users processed.
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
amount_centsRequiredinteger Amount in cents; must be a positive integer.
archivedboolean Moved into the archive table by the archiving task (read-only).
avatar_verinteger Avatar version, increases on every upload; empty when there is no avatar
balance_centsinteger 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
read-only
certifiedboolean Whether real-name verification has passed
client_ipstring 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
read-only
created_atstring Created at
read-only
currenciesAccountCurrencyOption[] 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.
currencyCurrencyBrief 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
read-only
currency_changeableboolean 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.
dataobject 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_currencystring 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_sessionboolean 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
read-only
desstring Description
directionstring credit = recharge (default), debit = deduct.
Values ["credit","debit"]Default "credit"
emailstring Email
enabledboolean Whether enabled
expires_atstring Expires at
freeze_reasonstring Freeze reason; empty if not frozen.
frozenboolean Whether the account is frozen; deductions are rejected while frozen.
idinteger Record ID
read-only
idsRequiredinteger[] User IDs to operate on, 1 to 100 per call.
ip_site_newboolean 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
read-only
ip_site_onboolean 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
read-only
last_used_atstring Time of last use; null if never used
ledger_idinteger ID of the linked ledger entry; null if none.
login_ip_allowstring[] Login IP allowlist (IPs or CIDRs); empty means no restriction
login_verifyLoginVerify 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)
Values ["none","email","sms"]
mch_order_nostring Merchant order number (the gateway-side order number); null for non-online payments.
namestring Name
nicknamestring Nickname; empty when not set (the UI shows the username)
paid_atstring Payment time; null if unpaid.
passwordstring 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_typestring admin/balance/alipay/wxpay, etc.; empty = unpaid.
phonestring Phone number
prefixstring First few characters of the plaintext key, for recognition
rate_to_basestring Rate at order time: 1 unit of this currency = ? base currency (decimal string, 8 places); later rate changes do not affect it.
remarkstring Remark
resetboolean When true, issue a new key; the old one stops working at once
rolestring Account role: admin or tenant
Values ["admin","tenant"]
scopesstring[] Granted scopes, same values as scopes at creation
secretstring Plaintext key (the X-API-Key value), returned only once at creation; only a hash is stored
statusstring Order status: unpaid or paid.
Values ["unpaid","paid"]
tenant_idinteger Owner tenant (user) ID
read-only
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.
totp_enabledboolean Whether TOTP is enabled
totp_recovery_leftinteger Number of unused TOTP recovery codes. Only present in GET /me and PUT /me when TOTP is enabled
read-only
transaction_idstring Gateway-side transaction ID; empty if unpaid.
typestring recharge (admin recharge) / deduct (admin deduction) / payment (online payment) / package (package purchase), etc.
unpaid_ordersinteger Number of unpaid orders (one of the blockers for changing the account currency). Only the admin GET /users/{user_id}/account returns it.
updated_atstring Updated at
read-only
user_idinteger User ID
usernamestring 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command