cdnca

API reference

/v1/identity

2 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
DELETE/v1/identity/session-families/{family_id}撤销当前用户的一个设备会话族Session
GET/v1/identity/sessions按设备会话族列出当前用户的登录会话Session

Contract file：api/control-identity-sessions.openapi.yaml

Operation details

DELETE /v1/identity/session-families/{family_id}

撤销当前用户的一个设备会话族

operationId
revokeCurrentIdentitySessionFamily
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

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

目标必须属于当前已认证 principal 的同一 scope/user。服务端在同一事务中重新锁定并校验 caller session、账户、membership 和 scope 后锁定整个 family。原 caller 仍有效时，精确重试 返回原响应；相同 Idempotency-Key 改变 family、revision、caller 或 request identity 返回 409。 撤销当前会话时，本次响应成功后当前 Bearer token 立即失效，后续请求先返回 401，不能绕过 caller 认证读取幂等收据。

Parameters

revokeCurrentIdentitySessionFamily Parameters
NameInTypeRequiredDescription
family_idpathstring(uuid)Yes—
X-Request-IDheaderstring(uuid)Yes—
If-MatchheaderstringYes列表返回的当前 family revision，必须使用强 ETag 形式
Idempotency-KeyheaderstringYes—

Responses

revokeCurrentIdentitySessionFamily Responses
StatusDescription
200已撤销或精确幂等重放

Fields：family_id: string(uuid) revision: integer(int64) revoked_at: string(date-time) current: boolean replayed?: boolean

400稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
401稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
404稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
405稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
409稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
500稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
503稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据

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.
  • 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.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/identity/sessions

按设备会话族列出当前用户的登录会话

operationId
listCurrentIdentitySessionFamilies
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

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

listCurrentIdentitySessionFamilies Parameters
NameInTypeRequiredDescription
X-Request-IDheaderstring(uuid)Yes—
limitqueryintegerNo—
cursorquerystringNo绑定当前 scope/user 和首次请求快照的稳定不透明游标

Responses

listCurrentIdentitySessionFamilies Responses
StatusDescription
200当前 principal 的会话族，按最新会话创建时间和 family_id 稳定倒序

Fields：items: array<SessionFamily> next_cursor?: string

400稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
401稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
405稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
500稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据
503稳定错误码和默认中文消息；不包含服务端原始错误或敏感会话数据

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