用途:该技能用于通过 Clerk 后端 API 管理身份数据,适用于用户查询、封禁、组织成员关系、邀请等场景。所有请求需携带 Bearer 令牌,沙箱/开发使用 sk_test_,生产使用 sk_live_,密钥来自 Clerk Dashboard → API Keys → Secret keys。
主要能力: 用户:统计(/v1/users/count)、列表(支持 limit 最大 500、offset、email_address、phone_number、username、user_id、external_id、organization_id、query、order_by)、按邮箱查用户、按 ID 查询、更新(PATCH)、封禁/解封、锁定/解锁、删除(硬删除并终止全部会话)、列出用户的组织成员关系。 组织:列表、按 ID 查询、列出成员、创建成员(含 role)、移除成员。 邀请:列出待处理邀请、创建邀请、撤销邀请。 会话:列表(可按 user_id、client_id、status 过滤)、撤销会话。
使用方式:所有请求以 https://api.clerk.com/v1 为基础地址,使用 curl 时添加 Authorization: Bearer $CLERK_TOKEN 请求头。写入类操作需写入 JSON 文件后通过 -d @/tmp/clerk_request.json 提交,并设置 Content-Type: application/json。排障可运行 zero doctor check-connector --env-name CLERK_TOKEN 或 zero doctor check-connector --url https://api.clerk.com/v1/users/count --method GET。
限制与注意:密钥按环境隔离,sk_test_* 仅适用于开发实例,sk_live_* 仅适用于生产;破坏性操作(删除、封禁、锁定、撤销)不可逆,执行前需核对目标 ID。后端 API 限制为每实例 1,000 请求/10 秒,遇到 HTTP 429 应使用指数退避。用户元数据分 public_metadata、private_metadata、unsafe_metadata 三类。官方文档见 https://clerk.com/docs/reference/backend-api。