接口详情
GET /v1/account/api-keys
List API keys owned by the current tenant user
- operationId
listSelfAPIKeys- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint requiring api_keys.self.manage. CdncaKey credentials are rejected. Each item includes the exact persisted IP allowlist; secret material is never returned.
参数
listSelfAPIKeys 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
listSelfAPIKeys 响应| 状态码 | 说明 |
|---|
200 | API key metadata only; secret material is never returned. 字段：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 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/api-keys
Create and activate an API key for the current tenant user
- operationId
createSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint requiring api_keys.self.manage. The secret is returned in this response only. A replay with the same identity, request, and Idempotency-Key deterministically returns the same secret. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
createSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | Collection creation precondition. Must be the quoted revision zero value. |
|---|
请求体
application/json · 必填：是
createSelfAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
createSelfAPIKey 响应| 状态码 | 说明 |
|---|
201 | Active key and its one-time secret. 字段：key: APIKey secret: string(password) |
|---|
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 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
503 | A required dependency is unavailable. |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/api-keys/{key_id}
Get API key metadata owned by the current tenant user
- operationId
getSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint requiring api_keys.self.manage. The exact persisted IP allowlist is returned; secret material is never returned.
参数
getSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
响应
getSelfAPIKey 响应| 状态码 | 说明 |
|---|
200 | Current API 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 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/account/api-keys/{key_id}
Update API key metadata
- operationId
updateSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint. Revoked keys cannot be updated. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
updateSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateSelfAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
updateSelfAPIKey 响应| 状态码 | 说明 |
|---|
200 | Updated 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 重试。
↑ 回到列表
POST /v1/account/api-keys/{key_id}/activate
Activate a pending API key and issue its secret
- operationId
activateSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint for the key owner. Only an unexpired pending_activation key can be activated; the secret is returned in this response only. The body carries the exact persisted IP allowlist. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
activateSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
activateSelfAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
activateSelfAPIKey 响应| 状态码 | 说明 |
|---|
200 | Activated key and one-time secret. 字段：key: APIKey secret: string(password) |
|---|
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/account/api-keys/{key_id}/revoke
Revoke an API key
- operationId
revokeSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint. Revocation immediately prevents future API key authentication. The body carries the exact persisted IP allowlist. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
revokeSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
revokeSelfAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
revokeSelfAPIKey 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
POST /v1/account/api-keys/{key_id}/rotate
Rotate an active API key secret
- operationId
rotateSelfAPIKey- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Session-only endpoint. The previous credential becomes invalid when the transaction commits. The body carries the exact persisted IP allowlist. An unknown result must be retried with the unchanged body, If-Match revision, and Idempotency-Key.
参数
rotateSelfAPIKey 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
key_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
rotateSelfAPIKey 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
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. |
|---|
响应
rotateSelfAPIKey 响应| 状态码 | 说明 |
|---|
200 | Updated key and one-time replacement secret. 字段：key: APIKey secret: string(password) |
|---|
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 重试。
↑ 回到列表
GET /v1/account/balance
Read the active tenant CNY balance
- operationId
getAccountBalance- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.account.read in a tenant scope. A platform identity cannot use this tenant endpoint.
响应
getAccountBalance 响应| 状态码 | 说明 |
|---|
200 | Current cached balance and optimistic revision. The balance is reconstructable from immutable postings. 字段：id: string(uuid) scope_id: string(uuid) tenant_id: string(uuid) tenant_name: string currency: string balance_minor: integer(int64) available_minor: integer(int64) refunding_minor: integer(int64) revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/inbox
List the tenant member's in-app messages (站内信), newest first
- operationId
listAccountInbox- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Tenant in-app notices addressed to the caller in the session's tenant scope (attack escalation security.escalate.blackhole once the blackhole is in force, security.escalate.cname_change_required). Written whatever the platform email/SMS settings say. Tenant-scope sessions only (platform sessions use /v1/admin/inbox). params holds the event's public template values; the console renders the text per language.
参数
listAccountInbox 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
unread | query | string: true | 否 | — |
|---|
page_size | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
响应
listAccountInbox 响应| 状态码 | 说明 |
|---|
200 | One page. 字段：items: array<object> unread: integer total: integer next_cursor: string unread_only: boolean page_size: integer |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
↑ 回到列表
POST /v1/account/inbox/read-all
Mark all the caller's in-app messages read (audited admin.inbox.read_all); read messages older than 180 days are pruned
- operationId
markAllAccountInboxMessagesRead- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
响应
markAllAccountInboxMessagesRead 响应| 状态码 | 说明 |
|---|
200 | Number of messages marked. 字段：marked: integer |
|---|
↑ 回到列表
GET /v1/account/inbox/unread-count
Unread message count for the header badge
- operationId
getAccountInboxUnreadCount- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
响应
getAccountInboxUnreadCount 响应| 状态码 | 说明 |
|---|
200 | Count. 字段：unread: integer |
|---|
401 | 认证失败或会话已失效。 |
|---|
失败时怎么办
↑ 回到列表
POST /v1/account/inbox/{message_id}/read
Mark one message read
- operationId
markAccountInboxMessageRead- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
markAccountInboxMessageRead 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
message_id | path | string(uuid) | 是 | — |
|---|
响应
markAccountInboxMessageRead 响应| 状态码 | 说明 |
|---|
204 | Read. |
|---|
404 | admin_inbox_message_not_found (not the caller's message). |
|---|
失败时怎么办
↑ 回到列表
GET /v1/account/ledger
List immutable entries for the active tenant CNY balance
- operationId
listAccountLedger- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.account.read and always derives scope from the authenticated tenant principal.
参数
listAccountLedger 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
响应
listAccountLedger 响应| 状态码 | 说明 |
|---|
200 | Newest-first tenant ledger page. 字段：items: array<BillingLedgerEntry> total: integer(int64) page: integer limit: integer |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/messages
List the current user's in-app messages
- operationId
listAccountMessages- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
listAccountMessages 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | — |
|---|
offset | query | integer | 否 | Page by position (page-number pagination). Cannot be combined with cursor. |
|---|
filter | query | string: read / unread | 否 | — |
|---|
响应
listAccountMessages 响应| 状态码 | 说明 |
|---|
200 | Inbox page 字段：items: array<InboxMessage> next_cursor?: string total?: integer |
|---|
400 | Stable API error |
|---|
401 | Stable API error |
|---|
403 | Stable API error |
|---|
500 | Stable API error |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/messages/{event_id}/delivered
Mark an in-app message delivered
- operationId
markMessageDelivered- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
markMessageDelivered 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
event_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
markMessageDelivered 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer | 是 | — |
|---|
响应
markMessageDelivered 响应| 状态码 | 说明 |
|---|
200 | Inbox state 字段：event_id: string(uuid) delivered_at?: string(date-time) read_at?: string(date-time) revision: integer replayed?: boolean |
|---|
400 | Stable API error |
|---|
401 | Stable API error |
|---|
403 | Stable API error |
|---|
404 | Stable API error |
|---|
409 | Stable API error |
|---|
415 | Stable API error |
|---|
500 | Stable API error |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/messages/{event_id}/read
Mark an in-app message read
- operationId
markMessageRead- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
markMessageRead 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
event_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
markMessageRead 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer | 是 | — |
|---|
响应
markMessageRead 响应| 状态码 | 说明 |
|---|
200 | Inbox state 字段：event_id: string(uuid) delivered_at?: string(date-time) read_at?: string(date-time) revision: integer replayed?: boolean |
|---|
400 | Stable API error |
|---|
401 | Stable API error |
|---|
403 | Stable API error |
|---|
404 | Stable API error |
|---|
409 | Stable API error |
|---|
415 | Stable API error |
|---|
500 | Stable API error |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/mfa
Read the authenticated account's current MFA state
- operationId
getMyMFAStatus- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Returns only inactive, enrollment_pending, or active plus non-sensitive credential metadata. No account label, seed, ciphertext, recovery code, or proof material is returned.
参数
getMyMFAStatus 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | Canonical W3C version 00 traceparent; the non-zero trace ID is used for correlation. |
|---|
响应
getMyMFAStatus 响应| 状态码 | 说明 |
|---|
200 | Current non-sensitive MFA state. |
|---|
400 | Request metadata, path, query, body, or input is invalid |
|---|
401 | Bearer session is absent, malformed, expired, revoked, or disabled |
|---|
403 | Live principal, tenant, permissions, or proof binding changed |
|---|
405 | Request method is not allowed. |
|---|
408 | Request was canceled |
|---|
503 | MFA, encryption, identity, IAM, or PostgreSQL dependency is unavailable |
|---|
504 | Request deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/mfa/disable
Disable active MFA after strong reauthentication
- operationId
disableMyMFA- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
A TOTP or unused recovery code is consumed in the same transaction as the immutable terminal fact and audit event. A same-payload Idempotency-Key retry is safe after an unknown commit result and returns 204 without re-consuming authentication evidence.
请求体
application/json · 必填：是
disableMyMFA 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
authentication | Authentication | 是 | — |
|---|
reason | string | 是 | — |
|---|
响应
disableMyMFA 响应| 状态码 | 说明 |
|---|
204 | Terminal fact already exists or was committed by this request. |
|---|
400 | Request metadata, path, query, body, or input is invalid |
|---|
401 | Bearer session is absent, malformed, expired, revoked, or disabled |
|---|
403 | Live principal, tenant, permissions, or proof binding changed |
|---|
405 | Request method is not allowed. |
|---|
409 | Idempotency, lifecycle, code replay, or bounded-use conflict |
|---|
412 | Active MFA is required |
|---|
413 | Request body exceeds the configured limit |
|---|
422 | MFA code or proof is invalid |
|---|
408 | Request was canceled |
|---|
503 | MFA, encryption, identity, IAM, or PostgreSQL dependency is unavailable |
|---|
504 | Request deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/mfa/enrollments
Begin TOTP enrollment
- operationId
beginMyMFAEnrollment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
A first successful response contains the seed and provisioning URI. A same-payload Idempotency-Key replay returns only credential_id, expires_at, and replayed=true; the service does not decrypt or reconstruct setup material during replay.
参数
beginMyMFAEnrollment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | Canonical W3C version 00 traceparent; the non-zero trace ID is used for correlation. |
|---|
请求体
application/json · 必填：是
beginMyMFAEnrollment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
account_label | string | 是 | — |
|---|
响应
beginMyMFAEnrollment 响应| 状态码 | 说明 |
|---|
201 | Enrollment created; secret and provisioning_uri are present exactly once. 字段：credential_id: string(uuid) secret: string provisioning_uri: string(uri) expires_at: string(date-time) replayed: const false |
|---|
200 | Enrollment replayed; secret and provisioning_uri are absent. 字段：credential_id: string(uuid) expires_at: string(date-time) replayed: const true |
|---|
400 | Request metadata, path, query, body, or input is invalid |
|---|
401 | Bearer session is absent, malformed, expired, revoked, or disabled |
|---|
403 | Live principal, tenant, permissions, or proof binding changed |
|---|
405 | Request method is not allowed. |
|---|
409 | Idempotency, lifecycle, code replay, or bounded-use conflict |
|---|
413 | Request body exceeds the configured limit |
|---|
408 | Request was canceled |
|---|
503 | MFA, encryption, identity, IAM, or PostgreSQL dependency is unavailable |
|---|
504 | Request deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/mfa/enrollments/{credential_id}/activate
Activate a pending TOTP credential
- operationId
activateMyMFAEnrollment- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Recovery codes are returned only by the first successful activation. They are omitted entirely from a same-payload Idempotency-Key replay.
参数
activateMyMFAEnrollment 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
credential_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
Traceparent | header | string | 是 | Canonical W3C version 00 traceparent; the non-zero trace ID is used for correlation. |
|---|
请求体
application/json · 必填：是
activateMyMFAEnrollment 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
code | string | 是 | — |
|---|
响应
activateMyMFAEnrollment 响应| 状态码 | 说明 |
|---|
201 | Enrollment activated; recovery_codes are present exactly once. 字段：credential_id: string(uuid) recovery_codes: array<string> activated_at: string(date-time) replayed: const false |
|---|
200 | Activation replayed; recovery_codes are absent. 字段：credential_id: string(uuid) activated_at: string(date-time) replayed: const true |
|---|
400 | Request metadata, path, query, body, or input is invalid |
|---|
401 | Bearer session is absent, malformed, expired, revoked, or disabled |
|---|
403 | Live principal, tenant, permissions, or proof binding changed |
|---|
405 | Request method is not allowed. |
|---|
409 | Idempotency, lifecycle, code replay, or bounded-use conflict |
|---|
410 | Enrollment or proof expired |
|---|
413 | Request body exceeds the configured limit |
|---|
422 | MFA code or proof is invalid |
|---|
408 | Request was canceled |
|---|
503 | MFA, encryption, identity, IAM, or PostgreSQL dependency is unavailable |
|---|
504 | Request deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/mfa/reset
Reset active MFA after strong reauthentication
- operationId
resetMyMFA- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Reset has the same atomic authentication, terminal-fact, audit, idempotency, and unknown commit semantics as disable. Account recovery without a TOTP or recovery code is a separate audited workflow and is not represented by this operation.
请求体
application/json · 必填：是
resetMyMFA 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
authentication | Authentication | 是 | — |
|---|
reason | string | 是 | — |
|---|
↑ 回到列表
POST /v1/account/mfa/step-up-proofs
Create a short-lived bound step-up proof
- operationId
createMyMFAStepUpProof- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
The proof is bound server-side to the authenticated user, scope, session, live permissions, tenant, audience, and action. The opaque token is returned only once and is omitted from replay. There is no client-accessible proof consume operation.
请求体
application/json · 必填：是
createMyMFAStepUpProof 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
audience | string | 是 | — |
|---|
action | string | 是 | — |
|---|
authentication | Authentication | 是 | — |
|---|
ttl_seconds | integer | 是 | — |
|---|
max_uses | integer | 是 | — |
|---|
响应
createMyMFAStepUpProof 响应| 状态码 | 说明 |
|---|
201 | Step-up proof created; token is present exactly once. 字段：proof_id: string(uuid) token: string method: string: totp / recovery_code issued_at: string(date-time) expires_at: string(date-time) max_uses: integer replayed: const false |
|---|
200 | Step-up proof replayed; token is absent. 字段：proof_id: string(uuid) method: string: totp / recovery_code issued_at: string(date-time) expires_at: string(date-time) max_uses: integer replayed: const true |
|---|
400 | Request metadata, path, query, body, or input is invalid |
|---|
401 | Bearer session is absent, malformed, expired, revoked, or disabled |
|---|
403 | Live principal, tenant, permissions, or proof binding changed |
|---|
405 | Request method is not allowed. |
|---|
409 | Idempotency, lifecycle, code replay, or bounded-use conflict |
|---|
410 | Enrollment or proof expired |
|---|
412 | Active MFA is required |
|---|
413 | Request body exceeds the configured limit |
|---|
422 | MFA code or proof is invalid |
|---|
408 | Request was canceled |
|---|
503 | MFA, encryption, identity, IAM, or PostgreSQL dependency is unavailable |
|---|
504 | Request deadline elapsed |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/notification-messages
List the current user's own event messages
- operationId
listOwnNotificationMessages- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Subscribable operational events (package, traffic, protection, certificate, site) delivered to the caller in the caller's own scope. Scope and recipient come from the session; announcements stay in the announcement inbox and system-required messages are excluded. site_id and package_id are facts recorded when the event was raised and remain after the resource is deleted.
参数
listOwnNotificationMessages 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
type | query | string | 否 | — |
|---|
site_id | query | string(uuid) | 否 | — |
|---|
package_id | query | string(uuid) | 否 | — |
|---|
site | query | string | 否 | Event-time site by exact display ID or case-insensitive substring of its current domain; events whose site no longer exists never match. |
|---|
package | query | string | 否 | User subscription by exact display ID or case-insensitive substring of the package name; events whose subscription no longer exists never match. |
|---|
limit | query | integer | 否 | — |
|---|
offset | query | integer | 否 | — |
|---|
响应
listOwnNotificationMessages 响应| 状态码 | 说明 |
|---|
200 | The caller's own event messages, newest first. 字段：schema: string items: array<OwnMessage> total: integer |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/notification-subscriptions/{event_type}
Read the current user's event subscription
- operationId
getNotificationSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
getNotificationSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
event_type | path | string | 是 | — |
|---|
响应
getNotificationSubscription 响应| 状态码 | 说明 |
|---|
200 | Current user's subscription or an identical natural replay. 字段：event_type: string sms_enabled: boolean email_enabled: boolean sms_supported: boolean email_supported: boolean inbox_enabled?: boolean email_bound?: boolean phone_bound?: boolean revision: integer(int64) changed: boolean |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
404 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PUT /v1/account/notification-subscriptions/{event_type}
Update the current user's event subscription
- operationId
updateNotificationSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
参数
updateNotificationSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
event_type | path | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
X-Request-ID | header | string | 否 | Correlation identifier and retry key for this write. Reusing the same value for the same authenticated actor and operation requires the exact original path, revision, and body; an exact retry replays the original response, while changed semantics return 409. |
|---|
请求体
application/json · 必填：是
updateNotificationSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
sms_enabled | boolean | 是 | — |
|---|
email_enabled | boolean | 是 | — |
|---|
inbox_enabled | boolean | 否 | Ticket events only (546): keep the in-app message-center copy. Omitted keeps the stored choice; any other event answers 400. |
|---|
响应
updateNotificationSubscription 响应| 状态码 | 说明 |
|---|
200 | Current user's subscription or an identical natural replay. 字段：event_type: string sms_enabled: boolean email_enabled: boolean sms_supported: boolean email_supported: boolean inbox_enabled?: boolean email_bound?: boolean phone_bound?: boolean revision: integer(int64) changed: boolean |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
404 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
409 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
415 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/orders
List tenant consumption records
- operationId
listAccountOrders- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.account.read. Callers with billing.order_records.read (tenant_owner) see all tenant users; other callers are restricted to their own user ID. Tenant rows are never editable.
参数
listAccountOrders 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
type | query | string: recharge / deduction / upgrade / purchase / renewal / package_change | 否 | — |
|---|
status | query | string: paid / unpaid | 否 | — |
|---|
search | query | string | 否 | Exact-page substring search over source-local display ID, UUID, user ID, username, email, or phone. |
|---|
created_from | query | string(date-time) | 否 | — |
|---|
created_to | query | string(date-time) | 否 | Exclusive upper bound. |
|---|
响应
listAccountOrders 响应| 状态码 | 说明 |
|---|
200 | Consumption record page 字段：items: array<AccountOrder> total: integer page: integer limit: integer can_manage: boolean |
|---|
400 | Invalid request fields |
|---|
401 | Authentication is required |
|---|
403 | Required permission is absent |
|---|
503 | Account order service unavailable |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/account/password
Re-authenticate and change the current tenant user's password
- operationId
changeAccountPassword- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Success revokes every existing session, including the session used for this request.
请求体
application/json · 必填：是
changeAccountPassword 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
current_password | string(password) | 是 | — |
|---|
new_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. |
|---|
响应
changeAccountPassword 响应| 状态码 | 说明 |
|---|
204 | Password changed and all sessions revoked. The client must sign in again. |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/account/profile
Get the current tenant user's profile
- operationId
getAccountProfile- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
响应
getAccountProfile 响应| 状态码 | 说明 |
|---|
200 | Current profile. 字段：id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/account/profile
Update the current tenant user's profile
- operationId
updateAccountProfile- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Changing email or phone requires current_password. A display-name-only update remains compatible without reauthentication.
参数
updateAccountProfile 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updateAccountProfile 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
display_name | string | 是 | — |
|---|
email | string(email) | null(email) | 是 | — |
|---|
phone | string | null | 是 | — |
|---|
current_password | string(password) | 否 | Required when the normalized email or phone differs from the current profile. |
|---|
响应
updateAccountProfile 响应| 状态码 | 说明 |
|---|
200 | Profile updated, or an identical idempotent request replayed. 字段：id: string(uuid) username: string display_name: string email: string(email) | null(email) phone: string | null 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 重试。
↑ 回到列表
GET /v1/account/statement
List the caller's merged consumption statement (orders, recharges and balance ledger entries)
- operationId
listAccountStatement- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires billing.account.read in the caller's own tenant scope. Merges manual order records, package and traffic-package orders, recharge orders and balance ledger postings that have no order row (manual adjustments, migration import credits, refund/void reversals, reseller sale/wholesale) into one newest-first page. Order-like rows are restricted to the caller's own user unless the caller holds billing.order_records.read; ledger rows belong to the tenant balance and follow the same visibility as GET /v1/account/ledger. Ledger operations that already have an order row (checkout debit, provider payment, recharge payment) are not repeated.
参数
listAccountStatement 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
type | query | string: recharge / deduction / upgrade / purchase / renewal / package_change / traffic_package / refund / income | 否 | — |
|---|
status | query | string: paid / unpaid | 否 | — |
|---|
created_from | query | string(date-time) | 否 | — |
|---|
created_to | query | string(date-time) | 否 | Exclusive upper bound. |
|---|
响应
listAccountStatement 响应| 状态码 | 说明 |
|---|
200 | Statement page 字段：items: array<AccountStatementEntry> total: integer(int64) page: integer limit: integer |
|---|
400 | Invalid request fields |
|---|
401 | Authentication is required |
|---|
403 | Required permission is absent |
|---|
503 | Account order service unavailable |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表