身份

概览

identity domain 管理你的后端所代表的产品用户。它签发、刷新和撤销 client session（面向 web 或 native 客户端的短期 client token），并发起和跟踪 external user 的数据删除。除读取删除状态外，这里的每个操作都需要 Idempotency-Key。

5 个操作 · SDK 资源：TypeScript cloud.identity · Python cloud.identity · Go cloud.Identity · API 总览

主要对象

• ClientSessionInput：创建 client session 的请求（客户端类型、请求的能力、可选的 ttl_seconds）。
• ClientSessionResponse：签发的 client token，以及其 session ID、client API URL 和过期时间。
• DeletionAccepted 与 Deletion：external user 数据删除的受理回执与状态。
• ExternalUserID：产品用户的不透明、应用内 ID。

ClientSessionInput

完整字段和使用该对象的方法见附录。

ClientSessionResponse

完整字段和使用该对象的方法见附录。

DeletionAccepted

完整字段和使用该对象的方法见附录。

Deletion

完整字段和使用该对象的方法见附录。

Binding

完整字段和使用该对象的方法见附录。

典型流程

1. 为已登录的产品用户调用 identity.createClientSession 创建会话，并把 token 交给客户端。
2. token 过期前，用 identity.refreshClientSession 轮换。
3. 用 identity.revokeClientSession 结束会话。
4. 要清除某个用户的数据，调用 identity.deleteExternalUser，它返回 DeletionAccepted；用 identity.getExternalUserDeletion 读取结果。

方法

identity.createClientSession

POST /v1/client-sessions · Operation ID createClientSession

创建 client session

签发 client token，ttl_seconds 作用于本次请求。省略时在幂等比较之前归一化为 600；用不同的归一化 TTL 复用同一个 Idempotency-Key 会返回 409 idempotency_conflict。

必须携带 Idempotency-Key。

SDK 方法

参数

请求体

application/json · 必填 · Schema: ClientSessionInput

响应

200 短期 client token · application/json · Schema: ClientSessionResponse

错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.identity.createClientSession({
  client_type: "web",
  requested_capabilities: ["example_requested_capabilities"]
}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.revokeClientSession

DELETE /v1/client-sessions/{sessionId} · Operation ID revokeClientSession

撤销 client session

必须携带 Idempotency-Key。

SDK 方法

参数

响应

204 会话已撤销，或此前已被撤销

无响应体。

错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.identity.revokeClientSession("session_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.refreshClientSession

POST /v1/client-sessions/{sessionId}/refresh · Operation ID refreshClientSession

刷新 client session

轮换 client token，ttl_seconds 作用于本次请求。省略时在幂等比较之前归一化为 600；用不同的归一化 TTL 复用同一个 Idempotency-Key 会返回 409 idempotency_conflict。

必须携带 Idempotency-Key。

SDK 方法

参数

请求体

application/json · 可选

响应

200 已轮换的 JTI，其能力与原来相同或更窄 · application/json · Schema: ClientSessionResponse

错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.identity.refreshClientSession("session_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.deleteExternalUser

DELETE /v1/external-users/{externalUserId} · Operation ID deleteExternalUser

开始删除外部用户数据

必须携带 Idempotency-Key。

SDK 方法

参数

响应

202 已接受异步删除 · application/json · Schema: DeletionAccepted

错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.identity.deleteExternalUser("external_user_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

identity.getExternalUserDeletion

GET /v1/external-users/{externalUserId}/deletions/{deletionId} · Operation ID getExternalUserDeletion

获取一次外部用户数据删除

不得携带 Idempotency-Key。

SDK 方法

参数

响应

200 限定于已认证应用的删除进度 · application/json · Schema: Deletion

错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.identity.getExternalUserDeletion("external_user_123", "deletion_123");
console.log(result);

按判别字段区分的结构

Binding 按 client_type 区分

Binding 的结构取决于它自己的 client_type 值。

ClientSessionInput 按 client_type 区分

ClientSessionInput 的结构取决于它自己的 client_type 值。