## 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.

Authentication: Admin only · Docs: https://www.gocdn888.com/en/docs/api/users

### GET `/api/v2/users`

List users · Authentication: Admin only

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `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 |  | Email |
| `phone` | string |  | Phone number |
| `username` | string |  | Username |

```sh
curl "https://panel.example.com/api/v2/users" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/users`

Create user · Authentication: Admin only

Request body:

| Field | Type | Required | 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 |  | Email |
| `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) Values: ["none","email","sms"] |
| `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 Values: ["admin","tenant"] |
| `totp_enabled` | boolean |  | Whether TOTP is enabled |
| `username` | string | Yes | Username |

```sh
curl -X POST "https://panel.example.com/api/v2/users" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/users/batch`

Batch enable, disable or delete users · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string | Yes | enable, disable or delete. Values: ["enable","disable","delete"] |
| `ids` | integer[] | Yes | User IDs to operate on, 1 to 100 per call. |

```sh
curl -X POST "https://panel.example.com/api/v2/users/batch" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/users/{id}`

Get user · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/users/{id}`

Update user · Authentication: Admin only

Request body:

| Field | Type | Required | 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 |  | Email |
| `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) Values: ["none","email","sms"] |
| `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 Values: ["admin","tenant"] |
| `totp_enabled` | boolean |  | Whether TOTP is enabled |
| `username` | string | Yes | Username |

```sh
curl -X PUT "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### DELETE `/api/v2/users/{id}`

Delete user · Authentication: Admin only

```sh
curl -X DELETE "https://panel.example.com/api/v2/users/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### GET `/api/v2/users/{user_id}/account`

Get user account · Authentication: Admin only

```sh
curl "https://panel.example.com/api/v2/users/{user_id}/account" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### PUT `/api/v2/users/{user_id}/account`

Freeze or unfreeze user account · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `freeze_reason` | string |  | Freeze reason; empty if not frozen. |
| `frozen` | boolean | Yes | Whether the account is frozen; deductions are rejected while frozen. |

```sh
curl -X PUT "https://panel.example.com/api/v2/users/{user_id}/account" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"freeze_reason":"风控核查","frozen":true}'
```

### GET `/api/v2/users/{user_id}/api-keys`

List a user's API keys · Authentication: Admin only

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `sort` | string |  | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |

```sh
curl "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/users/{user_id}/api-keys`

Create an API key for a user · Authentication: Admin only

Request body:

| Field | Type | Required | 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 |
| `name` | string | Yes | 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) |
| `scopes` | string[] | Yes | 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. |

```sh
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/api-keys" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"default","password":"${CURRENT_PASSWORD}","scopes":["*"]}'
```

### 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:

| Field | Type | Required | 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. |

```sh
curl -X PUT "https://panel.example.com/api/v2/users/{user_id}/api-keys/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password":"${CURRENT_PASSWORD}","reset":true}'
```

### DELETE `/api/v2/users/{user_id}/api-keys/{id}`

Delete a user's API key · Authentication: Admin only

```sh
curl -X DELETE "https://panel.example.com/api/v2/users/{user_id}/api-keys/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/users/{user_id}/recharges`

Recharge or deduct user balance · Authentication: Admin only

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer | Yes | 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. Values: ["credit","debit"] Default: "credit" |
| `remark` | string |  | Remark |

```sh
curl -X POST "https://panel.example.com/api/v2/users/{user_id}/recharges" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":10000,"direction":"credit","remark":"线下转账"}'
```

Users object:

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | string | Yes | enable, disable or delete. Values: ["enable","disable","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_cents` | integer | Yes | 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 (read-only) |
| `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 (read-only) |
| `created_at` | string |  | Created at (read-only) |
| `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 (read-only) |
| `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 (read-only) |
| `des` | string |  | Description |
| `direction` | string |  | credit = recharge (default), debit = deduct. Values: ["credit","debit"] Default: "credit" |
| `email` | string |  | Email |
| `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 (read-only) |
| `ids` | integer[] | Yes | 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 (read-only) |
| `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 (read-only) |
| `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) Values: ["none","email","sms"] |
| `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 Values: ["admin","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. Values: ["unpaid","paid"] |
| `tenant_id` | integer |  | Owner tenant (user) ID (read-only) |
| `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 (read-only) |
| `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 (read-only) |
| `user_id` | integer |  | User ID |
| `username` | string |  | Username |
