Operation details
GET /v1/reseller/customers
A reseller lists its own customers
- operationId
listResellerCustomers- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：reseller.customers.read
Description (from the contract)
Tenant session of an active reseller with reseller.customers.read or reseller.customers.manage. Items are the owner users of tenants whose parent_scope_id is the caller's scope (ManagedUser shape, metadata always set, group always null).
Parameters
listResellerCustomers Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
search | query | string | No | Username, name, email, phone or display ID substring. |
|---|
status | query | string: active / disabled | No | — |
|---|
Responses
listResellerCustomers Responses| Status | Description |
|---|
200 | One page of customers. Fields：items: array<ManagedUser> page: integer limit: integer total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
POST /v1/reseller/customers
A reseller opens a customer tenant under itself
- operationId
createResellerCustomer- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：reseller.customers.manage
Description (from the contract)
Creates tenant + tenant scope + owner user in one transaction with parent_scope_id = the caller's scope (the 480 guard re-checks the active reseller and customer_limit). Audit identity.user.create in both scopes. 422 reseller_customer_limit when the limit is reached; 409 username_conflict.
Parameters
createResellerCustomer Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createResellerCustomer Request body| Name | Type | Required | Description |
|---|
username | string | Yes | — |
|---|
password | string | Yes | 8 to 1024 printable ASCII characters (no space) with at least two of upper case, lower case, digits and symbols; otherwise password_policy_unmet. |
|---|
display_name | string | Yes | — |
|---|
email | string | null | No | — |
|---|
phone | string | null | No | — |
|---|
remark | string | null | No | — |
|---|
qq | string | null | No | — |
|---|
Responses
createResellerCustomer Responses| Status | Description |
|---|
201 | The customer's owner user. Fields：id: string(uuid) display_id: string scope_id: string(uuid) tenant_id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null status: string: active / disabled role: string: tenant_owner / tenant_viewer group_id: string(uuid) | null(uuid) group_name: string | null metadata?: ManagedUserMetadata verification?: ManagedUserVerification reseller?: ManagedUserReseller revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
422 | The request is well formed but breaks a business rule (error.code names it). |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/reseller/customers/{scope_id}/sites
A reseller lists one of its customers' sites (read only)
- operationId
listResellerCustomerSites- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：reseller.customers.read
Description (from the contract)
Tenant session of an active reseller with reseller.customers.read or reseller.customers.manage. The scope must be a customer tenant under the caller's active reseller scope (same check as the reseller package-commerce routes); any other scope, the caller's own included, is 403. Items carry only id, display_id and domain, newest first.
Parameters
listResellerCustomerSites Parameters| Name | In | Type | Required | Description |
|---|
scope_id | path | string(uuid) | Yes | The customer's tenant scope ID. |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
domain | query | string | No | Case-insensitive domain substring. |
|---|
Responses
listResellerCustomerSites Responses| Status | Description |
|---|
200 | One page of the customer's sites. Fields：items: array<object> page: integer limit: integer total: integer(int64) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
PUT /v1/reseller/customers/{user_id}/status
A reseller suspends (disabled) or resumes (active) one of its customers
- operationId
setResellerCustomerStatus- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：reseller.customers.manage
Description (from the contract)
Only the owner user of the caller's own customer tenant; anything else is 404. Disabling revokes the user's sessions. Audit reseller.customer.status in both scopes. 409 version_conflict on a stale expected_revision.
Parameters
setResellerCustomerStatus Parameters| Name | In | Type | Required | Description |
|---|
user_id | path | string(uuid) | Yes | — |
|---|
Request body
application/json · Required：Yes
setResellerCustomerStatus Request body| Name | Type | Required | Description |
|---|
status | string: active / disabled | Yes | — |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
setResellerCustomerStatus Responses| Status | Description |
|---|
200 | The customer's owner user after the change. Fields：id: string(uuid) display_id: string scope_id: string(uuid) tenant_id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null status: string: active / disabled role: string: tenant_owner / tenant_viewer group_id: string(uuid) | null(uuid) group_name: string | null metadata?: ManagedUserMetadata verification?: ManagedUserVerification reseller?: ManagedUserReseller revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list