接口详情
GET /v1/admin/users
List tenant users in the customer control plane
- operationId
listManagedUsers- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires identity.users.manage in a platform scope. Platform identities are never returned.
参数
listManagedUsers 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
include | query | array<string: user_metadata / user_verification / platform_admins / reseller> | 否 | Optional comma-separated unique projections. user_metadata adds remark and QQ; user_verification adds only current personal/company verification flags; platform_admins also lists platform-scope administrators (tenant_id null); Omission preserves the original fifteen-field representation. Empty, unknown, duplicate items and repeated parameters are rejected. user_verification, platform_admins and reseller are accepted only on this list endpoint. |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
search | query | string | 否 | — |
|---|
display_id | query | string | 否 | Exact positive-decimal user display ID. Internal UUID identity and write paths are unchanged. |
|---|
username | query | string | 否 | Case-insensitive literal substring of username only. Trim boundary whitespace, reject raw C0/C1 controls, and allow at most 128 Unicode code points after trimming. Empty means no filter; all supplied filters intersect using AND. |
|---|
display_name | query | string | 否 | Case-insensitive literal substring of display name only, with the same trimming, control-character rejection, length and AND semantics as username. Percent and underscore are literal characters. |
|---|
email | query | string | 否 | Case-insensitive literal substring of email only, with the same trimming, control-character rejection, length and AND semantics as username. Partial addresses are allowed; NULL email does not match a nonempty filter. |
|---|
phone | query | string | 否 | Case-insensitive literal substring of phone only, with the same trimming, control-character rejection, length and AND semantics as username. Leading zeroes and plus signs are significant; NULL phone does not match a nonempty filter. |
|---|
remark | query | string | 否 | Trimmed case-insensitive literal substring of the administrator remark. Empty means no filter; combined with every other filter using AND. |
|---|
qq | query | string | 否 | Trimmed case-insensitive literal substring of the QQ contact text. Leading zeroes are significant; empty means no filter and all filters intersect. |
|---|
status | query | string: active / disabled | 否 | — |
|---|
real_name_status | query | string: verified / unverified | 否 | Optional current verification filter, intersected with all other filters before pagination in the same snapshot as the returned flags. verified means personal_verified OR company_verified; unverified means neither. Omit for all users. Empty or unknown values are invalid. Each flag requires the latest application of that kind to be approved, its authoritative identity binding to match, and its evidence settlement to be settled. Reads never create or approve identity records. |
|---|
role | query | string: tenant_owner / tenant_viewer | 否 | — |
|---|
group_id | query | string(uuid) | 否 | — |
|---|
type | query | string: reseller / customer / direct | 否 | reseller = the tenant has a reseller profile (active or suspended); customer = the tenant belongs to a reseller; direct = neither. Any value excludes platform administrators. Omit for all users. |
|---|
parent | query | string | 否 | Owning reseller filter, applied before pagination and intersected with type. none = tenants without a reseller (platform customers, including resellers themselves); a lowercase reseller scope UUID = that reseller's customers. Excludes platform administrators. Omit for all users. |
|---|
响应
listManagedUsers 响应| 状态码 | 说明 |
|---|
200 | Stable tenant user page ordered newest first. 字段：items: array<ManagedUser> page: integer limit: integer total: integer(int64) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/users
Create an isolated tenant user
- operationId
createManagedUser- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Creates the tenant, tenant scope, system roles, membership, and Argon2id credential atomically.
参数
createManagedUser 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
include | query | string: user_metadata | 否 | Set to user_metadata to include administrator-only remark and QQ fields. Omission preserves the original fifteen-field representation. Unknown or repeated values are rejected. This representation choice does not change mutation idempotency; a historical receipt may omit metadata, in which case read the current resource before editing these fields. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Caller-stable write attempt identifier. Reuse it only with the same idempotency key and body. |
|---|
traceparent | header | string | 否 | W3C trace context preserved across an exact retry. |
|---|
请求体
application/json · 必填：是
createManagedUser 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
username | string | 是 | — |
|---|
password | string(password) | 是 | 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 | 是 | — |
|---|
email | string(email) | null(email) | 否 | — |
|---|
phone | string | null | 否 | — |
|---|
remark | string | null | 否 | Administrator-only remark, trimmed at both ends. Internal tabs and line breaks are preserved; other control characters are rejected. Null or whitespace-only input clears the stored value. Length counts Unicode code points. |
|---|
qq | string | null | 否 | Trimmed QQ contact text, preserving leading zeroes. Not a login identifier and not unique. Control characters are rejected; null or whitespace-only input clears the stored value. Length counts Unicode code points. |
|---|
role | string: tenant_owner / tenant_viewer | 是 | — |
|---|
group_id | string(uuid) | null(uuid) | 否 | — |
|---|
响应
createManagedUser 响应| 状态码 | 说明 |
|---|
201 | Tenant user created, or an identical idempotent request replayed. 字段：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 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/admin/users
Atomically update tenant users
- operationId
batchUpdateManagedUsers- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Applies the complete array or no changes. Disabling a user revokes every refresh family and invalidates existing access sessions immediately.
参数
batchUpdateManagedUsers 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
include | query | string: user_metadata | 否 | Set to user_metadata to include administrator-only remark and QQ fields. Omission preserves the original fifteen-field representation. Unknown or repeated values are rejected. This representation choice does not change mutation idempotency; a historical receipt may omit metadata, in which case read the current resource before editing these fields. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Caller-stable write attempt identifier. Reuse it only with the same idempotency key and body. |
|---|
traceparent | header | string | 否 | W3C trace context preserved across an exact retry. |
|---|
请求体
application/json · 必填：是
响应
batchUpdateManagedUsers 响应| 状态码 | 说明 |
|---|
200 | Users updated in request order, or an identical idempotent request replayed. 字段：items: array<ManagedUser> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/users/{id}
Get one tenant user
- operationId
getManagedUser- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
A platform identity or an unknown tenant user produces the same 404 response.
参数
getManagedUser 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
include | query | string: user_metadata | 否 | Set to user_metadata to include administrator-only remark and QQ fields. Omission preserves the original fifteen-field representation. Unknown or repeated values are rejected. This representation choice does not change mutation idempotency; a historical receipt may omit metadata, in which case read the current resource before editing these fields. |
|---|
id | path | string(uuid) | 是 | — |
|---|
响应
getManagedUser 响应| 状态码 | 说明 |
|---|
200 | Tenant user details. 字段：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 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/admin/users/{id}
Update tenant user profile, status, and role
- operationId
updateManagedUser- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Disabling a user revokes every refresh family and invalidates existing access sessions immediately.
参数
updateManagedUser 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
include | query | string: user_metadata | 否 | Set to user_metadata to include administrator-only remark and QQ fields. Omission preserves the original fifteen-field representation. Unknown or repeated values are rejected. This representation choice does not change mutation idempotency; a historical receipt may omit metadata, in which case read the current resource before editing these fields. |
|---|
id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Caller-stable write attempt identifier. Reuse it only with the same idempotency key and body. |
|---|
traceparent | header | string | 否 | W3C trace context preserved across an exact retry. |
|---|
请求体
application/json · 必填：是
updateManagedUser 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
display_name | string | 是 | — |
|---|
email | string(email) | null(email) | 是 | — |
|---|
phone | string | null | 是 | — |
|---|
status | string: active / disabled | 是 | — |
|---|
remark | string | null | 否 | Administrator-only remark, trimmed at both ends. Internal tabs and line breaks are preserved; other control characters are rejected. Null or whitespace-only input clears the stored value. Length counts Unicode code points. |
|---|
qq | string | null | 否 | Trimmed QQ contact text, preserving leading zeroes. Not a login identifier and not unique. Control characters are rejected; null or whitespace-only input clears the stored value. Length counts Unicode code points. |
|---|
role | string: tenant_owner / tenant_viewer | 是 | — |
|---|
group_id | string(uuid) | null(uuid) | 否 | — |
|---|
响应
updateManagedUser 响应| 状态码 | 说明 |
|---|
200 | User updated, or an identical idempotent request replayed. 字段：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 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/users/{id}/login-security
Read the selected tenant user's login security policy
- operationId
getManagedUserLoginSecurity- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires an active primary platform bearer session and identity.users.manage. API keys and impersonation sessions are rejected. A missing policy returns revision 0, none, and an empty allowlist.
参数
getManagedUserLoginSecurity 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant membership scope. Duplicate or unknown query parameters are rejected. |
|---|
响应
getManagedUserLoginSecurity 响应| 状态码 | 说明 |
|---|
200 | Independent policy, without user profile or contact information. 字段：user_id: string(uuid) tenant_scope_id: string(uuid) revision: integer(int64) login_verification: string: none / sms / email login_allowlist: array<string> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/admin/users/{id}/login-security
Replace a tenant user's login security policy
- operationId
updateManagedUserLoginSecurity- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Same primary-session authorization as GET. The policy uses its own revision, receipt and audit; it does not change users.revision or existing user-write receipts. All fields are required. Empty allowlist disables the source restriction; none disables the additional login code. Email/SMS require a bound contact and a configured enabled channel. Source restrictions apply to new password and code logins, not existing sessions, refresh or API keys. Once a policy is enabled, rolling back to a binary without the login gate is unsafe. The service never silently clears a policy to permit rollback.
参数
updateManagedUserLoginSecurity 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant membership scope. Duplicate or unknown query parameters are rejected. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Caller-stable write attempt identifier. Reuse it only with the same idempotency key and body. |
|---|
traceparent | header | string | 否 | W3C trace context preserved across an exact retry. |
|---|
请求体
application/json · 必填：是
updateManagedUserLoginSecurity 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
login_verification | string: none / sms / email | 是 | — |
|---|
login_allowlist | array<string> | 是 | IPv4/IPv6 addresses or CIDR prefixes (for example 203.0.113.0/24). Ports, zones and empty entries are rejected. The service unmaps IPv4-mapped IPv6, masks prefixes to their network, collapses full-length prefixes to the address, deduplicates and sorts. Empty clears the restriction. |
|---|
响应
updateManagedUserLoginSecurity 响应| 状态码 | 说明 |
|---|
200 | Saved policy or exact original receipt on replay. Clearing retains and increments its revision. 字段：user_id: string(uuid) tenant_scope_id: string(uuid) revision: integer(int64) login_verification: string: none / sms / email login_allowlist: array<string> |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
422 | login_security_contact_required; the selected channel has no bound contact. |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/users/{id}/secondary-verification
Read the selected tenant user's secondary identity verification request
- operationId
getManagedUserSecondaryVerification- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Same primary-session authorization as login-security. A missing request returns revision 0, disabled, expiry_action none.
参数
getManagedUserSecondaryVerification 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant membership scope. Duplicate or unknown query parameters are rejected. |
|---|
响应
getManagedUserSecondaryVerification 响应| 状态码 | 说明 |
|---|
200 | Request with derived completion state. 字段：user_id: string(uuid) tenant_scope_id: string(uuid) revision: integer(int64) enabled: boolean deadline: string(date-time) | null expiry_action: string: none / lock_sites requested_at: string(date-time) | null completed: boolean enforced_at: string(date-time) | null |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/admin/users/{id}/secondary-verification
Replace a tenant user's secondary identity verification request
- operationId
updateManagedUserSecondaryVerification- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Own revision, receipt and audit; users.revision is unchanged. Switching it on records requested_at and enqueues the identity.secondary_verification email/SMS notice in the same transaction; editing an active request does not notify again. The user completes it with an approved personal_reverification created after requested_at. expiry_action lock_sites requires a deadline; when the deadline passes without completion the control plane stops the user's sites (disables and locks them, then republishes so the nodes stop serving them). Once the reverification is approved, or the request is switched off or its deadline moved into the future, exactly the changes it made are undone and the scope is republished; sites stopped or locked for other reasons are left as they are. Disabling requires deadline null and expiry_action none.
参数
updateManagedUserSecondaryVerification 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant membership scope. Duplicate or unknown query parameters are rejected. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Caller-stable write attempt identifier. Reuse it only with the same idempotency key and body. |
|---|
traceparent | header | string | 否 | W3C trace context preserved across an exact retry. |
|---|
请求体
application/json · 必填：是
updateManagedUserSecondaryVerification 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
enabled | boolean | 是 | — |
|---|
deadline | string(date-time) | null | 否 | — |
|---|
expiry_action | string: none / lock_sites | 是 | — |
|---|
响应
updateManagedUserSecondaryVerification 响应| 状态码 | 说明 |
|---|
200 | Saved request or exact original receipt on replay. 字段：user_id: string(uuid) tenant_scope_id: string(uuid) revision: integer(int64) enabled: boolean deadline: string(date-time) | null expiry_action: string: none / lock_sites requested_at: string(date-time) | null completed: boolean enforced_at: string(date-time) | null |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
503 | A required dependency is unavailable. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/users/{user_id}/api-keys
List a tenant user's API key metadata
- operationId
listManagedUserAPIKeys- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Platform session-only endpoint requiring api_keys.admin.manage. Each item includes the exact persisted IP allowlist; secrets are never returned.
参数
listManagedUserAPIKeys 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
user_id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant scope selected by the platform administrator. |
|---|
limit | query | integer | 否 | — |
|---|
status | query | string: pending_activation / active / revoked | 否 | — |
|---|
name | query | string | 否 | — |
|---|
key_id | query | string | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
offset | query | integer | 否 | Page-number access (canonical non-negative integer, 0-10000). Cannot be combined with cursor; an offset past the end returns empty items with total. |
|---|
usable | query | string: true | 否 | Only `true` is accepted. Keeps keys that can authenticate at the page snapshot: status active and expires_at absent or later than snapshot_at. An expired key keeps its active lifecycle status as history, so status=active alone does not mean usable. Combinable only with status=active or no status. Clients judge expiry against the response Date header (server clock), not their own clock. |
|---|
响应
listManagedUserAPIKeys 响应| 状态码 | 说明 |
|---|
200 | Target user's API key metadata. 字段：items: array<APIKey> next_cursor: string has_more: boolean total?: integer |
|---|
400 | Malformed JSON, UUID, revision, CIDR, duplicate or overlapping prefix, or more than 32 prefixes. Validation params expose only field indexes and counts, never any submitted CIDR, secret, digest, or matching prefix. |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/users/{user_id}/api-keys
Create pending API key metadata for a tenant user
- operationId
createPendingManagedUserAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Platform session-only endpoint requiring api_keys.admin.manage. No secret is created or returned. The target user must activate the key with their own bearer session before it can authenticate. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
createPendingManagedUserAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
user_id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant scope selected by the platform administrator. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Collection creation precondition. Must be the quoted revision zero value. |
|---|
请求体
application/json · 必填：是
createPendingManagedUserAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
scopes | array<string> | 是 | — |
|---|
ip_allowlist | array<string> | 否 | Canonical network CIDRs only: no host bits, zones, IPv4-mapped IPv6, duplicate prefixes, or overlaps. Empty means unrestricted. |
|---|
expires_at | string(date-time) | 否 | Must be in the future and no more than 366 days from the server clock. |
|---|
pending_ttl_seconds | integer(int64) | 否 | — |
|---|
响应
createPendingManagedUserAPIKey 响应| 状态码 | 说明 |
|---|
201 | Pending API key metadata without secret material. 字段：id: string(uuid) key_id: string key_prefix: string scope_id: string(uuid) tenant_id: string(uuid) user_id: string(uuid) name: string scopes: array<string> unavailable_scopes?: array<string> ip_allowlist: array<string> status: string: pending_activation / active / revoked pending_expires_at?: string(date-time) expires_at?: string(date-time) last_used_at?: string(date-time) activated_at?: string(date-time) revoked_at?: string(date-time) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Malformed JSON, UUID, revision, CIDR, duplicate or overlapping prefix, or more than 32 prefixes. Validation params expose only field indexes and counts, never any submitted CIDR, secret, digest, or matching prefix. |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
503 | A required dependency is unavailable. |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/users/{user_id}/api-keys/{key_id}/revoke
Revoke a tenant user's API key
- operationId
revokeManagedUserAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Platform session-only endpoint. Administrators cannot activate, rotate, or read key secrets. The body carries the exact persisted IP allowlist. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
revokeManagedUserAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
user_id | path | string(uuid) | 是 | — |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
tenant_scope_id | query | string(uuid) | 是 | Exact tenant scope selected by the platform administrator. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
revokeManagedUserAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
ip_allowlist | array<string> | 是 | Canonical network CIDRs only: no host bits, zones, IPv4-mapped IPv6, duplicate prefixes, or overlaps. Empty means unrestricted. |
|---|
grant_all_scopes | boolean | 否 | Rotate only. When true, the rotation also replaces the key scopes with every permission the current session may grant to an API key (the simple-mode "reset key"). It is part of the idempotency binding. Other operations reject true with 400 invalid_request. |
|---|
响应
revokeManagedUserAPIKey 响应| 状态码 | 说明 |
|---|
200 | Revoked key metadata. 字段：id: string(uuid) key_id: string key_prefix: string scope_id: string(uuid) tenant_id: string(uuid) user_id: string(uuid) name: string scopes: array<string> unavailable_scopes?: array<string> ip_allowlist: array<string> status: string: pending_activation / active / revoked pending_expires_at?: string(date-time) expires_at?: string(date-time) last_used_at?: string(date-time) activated_at?: string(date-time) revoked_at?: string(date-time) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Malformed JSON, UUID, revision, CIDR, duplicate or overlapping prefix, or more than 32 prefixes. Validation params expose only field indexes and counts, never any submitted CIDR, secret, digest, or matching prefix. |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
503 | A required dependency is unavailable. |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表