选项上下文
用户提示: $ARGUMENTS
关键: 每次写请求前的强制性检查
在任何 POST / PATCH / PUT / DELETE 之前,您必须在响应中完成以下所有检查:
-
检查 CLERK_SECRET_KEY — 确认已设置:
echo $CLERK_SECRET_KEY | head -c 10如果为空,请停止并询问用户。没有有效密钥则无法继续。
-
检查 CLERK_BAPI_SCOPES — 运行:
echo $CLERK_BAPI_SCOPES检查输出。如果缺少作用域或不包含所需的写权限,请告知用户: "这是一个写操作,您当前的作用域可能不允许。使用 --admin 重新运行以绕过?" 不要尝试请求并失败 — 先询问。
-
对于 DELETE 请求: 明确警告该操作是不可逆的,并准确列出将被永久销毁的数据(用户记录、所有会话、所有成员资格、所有关联数据)。要求用户明确确认后才能继续。此警告是强制性的 — 绝不能跳过。
-
对于元数据操作: 始终解释正在使用的元数据类型及其原因(参见下面的元数据类型部分)。
快速路径: 常见操作(直接使用,无需获取规范)
对于以下操作,跳过规范获取,直接使用这些确切的模板。根据用户上下文替换 $CLERK_SECRET_KEY、$USER_ID、$ORG_ID、$EMAIL。
创建组织 + 邀请成员(两步)
# 步骤 1 — 创建组织
ORG=$(curl -s -X POST "https://api.clerk.com/v1/organizations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}")
echo "$ORG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"
# 步骤 2 — 提取组织 ID
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
# 步骤 3 — 邀请成员并指定角色
curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d "{\"email_address\": \"[email protected]\", \"role\": \"org:admin\"}" \
| python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"
角色: 使用 "org:admin" 或 "org:member"(始终以 org: 为前缀)。
SDK 等效项(适用于 Next.js / TypeScript 项目,使用 @clerk/nextjs 或 @clerk/backend)
import { clerkClient } from '@clerk/nextjs/server'
// 或如果直接使用 @clerk/backend:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })
// 步骤 1: 创建组织
const org = await clerkClient.organizations.createOrganization({
name: 'Acme Corp',
createdBy: userId, // 必填 — 创建组织的用户 ID
})
// 步骤 2: 邀请成员加入组织
const invitation = await clerkClient.organizations.createOrganizationInvitation({
organizationId: org.id,
emailAddress: '[email protected]',
role: 'org:admin', // 或 'org:member'
})
更新用户元数据
始终先解释三种元数据类型,然后再询问使用哪一种:
| 类型 | 字段 | 可读取方 | 可写入方 | 用途 |
|---|---|---|---|---|
| 公开 | public_metadata | 客户端 + 服务端 | 仅服务端 | 前端读取的计划层级、角色、功能标志 |
| 私有 | private_metadata | 仅服务端 | 仅服务端 | Stripe ID、合规标志、内部标识符 |
| 不安全 | unsafe_metadata | 客户端 + 服务端 | 客户端 + 服务端 | 临时 UI 状态、引导步骤(客户端可写 — 避免敏感数据) |
对于 plan: 'pro' 和 onboarded: true — 使用 public_metadata(前端可读,服务端可写):
curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"public_metadata": {"plan": "pro", "onboarded": true}}' \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Updated user {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')]"
SDK 等效项:
import { clerkClient } from '@clerk/nextjs/server'
// 或: import { createClerkClient } from '@clerk/backend'
await clerkClient.users.updateUser(userId, {
publicMetadata: { plan: 'pro', onboarded: true }, // 客户端可读,仅服务端可写
// privateMetadata: { stripeId: 'cus_xxx' }, // 仅服务端读写
// unsafeMetadata: { step: 'welcome' }, // 客户端可写,避免敏感数据
})
注意: REST API 使用 snake_case (public_metadata)。SDK 使用 camelCase (publicMetadata)。
列出用户(过去 7 天)
curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
print(f'找到 {len(data)} 个用户:')
for u in data:
print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"无邮箱\")}')
else:
print(json.dumps(data, indent=2))
"
删除用户(需要确认)
# 仅在得到用户明确确认后运行
curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'已删除: {d}')"
Clerk 后端 API — 完整端点参考
基础 URL: https://api.clerk.com/v1
认证: 每个请求都需包含 Authorization: Bearer $CLERK_SECRET_KEY。
用户
列出用户
GET /v1/users
查询参数: limit (最大 500, 默认 10), offset, order_by (+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at), email_address[], phone_number[], username[], web3wallet[], user_id[], query, created_at (ISO 8601 范围: gt:TIMESTAMP 或 lt:TIMESTAMP, 单位为 Unix 毫秒)
返回: User 对象数组
获取用户
GET /v1/users/{user_id}
返回: User 对象
更新用户
PATCH /v1/users/{user_id}
请求体 (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }
删除用户 — 不可逆
DELETE /v1/users/{user_id}
销毁: 用户记录、所有会话、所有成员资格、所有关联数据
返回: { id, object, deleted: true }
始终警告用户这是永久性操作,并在继续前请求确认。
组织
创建组织
POST /v1/organizations
请求体: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
返回: Organization 对象,包含 { id, name, slug, ... }
列出组织
GET /v1/organizations
查询参数: limit, offset, query, order_by
邀请成员
POST /v1/organizations/{organization_id}/invitations
请求体: { email_address: string, role: string ("org:admin" 或 "org:member"), public_metadata?, private_metadata? }
返回: OrganizationInvitation 对象
如何执行请求
始终使用直接的 curl 命令执行请求。 使用规范提取脚本 (api-specs-context.sh、extract-tags.js、extract-endpoint-detail.sh) 来发现端点,但使用 curl 发出实际的 API 调用。不要使用 scripts/execute-request.sh — 它是本地开发辅助工具,不适用于代理使用。
GET 请求模板:
curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
POST/PATCH 请求模板:
curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '${BODY_JSON}'
DELETE 请求模板:
curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
-H "Authorization: Bearer $CLERK_SECRET_KEY"
获取响应后: 解析并清晰地显示。使用 python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" 美化打印 JSON。提取关键字段(id、email、name 等)并为用户总结。
API 规范上下文
在执行快速路径之外的任何操作之前,通过运行以下命令获取可用的规范版本和标签:
bash scripts/api-specs-context.sh
使用输出来确定最新版本和可用的标签。
缓存: 如果您在此对话中已经获取过规范上下文,请不要再次获取。重用先前调用中的版本和标签。
规则
- 对于常见操作(列出用户、创建组织、邀请、更新元数据、删除用户):使用上面的快速路径 — 不要先获取规范。
- 始终忽略与
platform相关的端点/模式。 - 在执行写请求(POST/PUT/PATCH/DELETE)之前,始终请求确认。
- 对于 DELETE 操作,始终警告用户该操作是不可逆的,并提及将丢失哪些数据(用户记录、会话、成员资格)。此警告是强制性的 — 绝不能跳过。
- 对于写操作(POST/PUT/PATCH/DELETE),在尝试请求之前检查
CLERK_BAPI_SCOPES。如果缺少或不足,请预先询问用户。不要尝试并失败 — 执行前询问。此检查是强制性的。 - 对于元数据操作,始终解释所有三种类型(public、private、unsafe)并推荐合适的类型。
- 分页:始终使用
limit+offset,并提及对于大型数据集,结果可能会分页。 - 对所有 API 调用使用直接的 curl 命令 — 永不使用
scripts/execute-request.sh。
速率限制与注意事项
速率限制
| 环境 | 限制 |
|---|---|
| 生产环境 | 1,000 请求 / 10 秒 |
| 开发环境 | 100 请求 / 10 秒 |
| 单次邀请 | 100 / 小时 |
| 批量邀请 | 25 / 小时 |
| 组织邀请 | 250 / 小时 |
| 前端 API 登录创建 | 5 / 10 秒 |
| 前端 API 登录尝试 | 3 / 10 秒 |
| 列出用户每页最大 | 500 |
currentUser() 会进行实际的 API 调用,计入速率限制。如果仅需要会话声明,请使用 auth() — 它从令牌中读取,无需 API 调用。
元数据覆盖(非合并)
updateUser({ publicMetadata: { role: 'admin' } }) 替换所有公共元数据,而非合并。要在不丢失现有数据的情况下添加字段:先读取,展开,再写入。
错误做法:
await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })
这会删除所有其他 publicMetadata 字段。
正确做法:
const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
publicMetadata: { ...user.publicMetadata, newField: 'value' },
})
模式
根据 选项上下文 中的用户提示确定活动模式:
| 模式 | 触发器 | 行为 |
|---|---|---|
help | 提示为空,或仅包含 help / -h / --help | 打印用法示例(步骤 0) |
browse | 提示为 tags,或标签名称(例如 Users) | 列出所有标签或某个标签的端点 |
execute | 特定端点(例如 GET /users)或自然语言操作(例如 "get user john_doe") | 查找端点,执行请求 |
detail | 端点 + help / -h / --help(例如 GET /users help) | 显示端点模式,不执行 |
您的任务
默认使用 API 规范上下文中的最新版本。如果用户指定了不同的版本(例如 --version 2024-10-01),则使用该版本。
确定活动模式,然后按照下面的适用步骤操作。
0. 打印用法
模式: 仅 help — 对于 browse、execute 和 detail 则跳过。
向用户逐字打印以下示例:
浏览
/clerk-backend-api tags — 列出所有标签
/clerk-backend-api Users — 浏览 Users 标签的端点
/clerk-backend-api Users version 2025-11-10.yml — 使用不同版本浏览
执行
/clerk-backend-api GET /users — 获取所有用户
/clerk-backend-api get user john_doe — 自然也支持自然语言
/clerk-backend-api POST /invitations — 创建邀请
检查
/clerk-backend-api GET /users help — 显示端点模式,不执行
/clerk-backend-api POST /invitations -h — 查看请求/响应详细信息
选项
--admin — 为写/删除操作绕过作用域限制
--version [date], version [date] — 使用特定的规范版本
--help, -h, help — 检查端点,而非执行
在此停止。
1. 获取标签
模式: browse(当提示为 tags 或未指定标签时)— 对于 help、execute 和 detail 则跳过。
如果使用非最新版本,请获取该版本的标签:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js
否则,使用 API 规范上下文中已有的标签。
在表格中分享标签,并提示用户选择一个查询。
2. 获取标签端点
模式: browse(当提供了标签名称时)— 对于 help、execute 和 detail 则跳过。
获取标识标签的所有端点:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"
与用户分享结果(端点、模式、参数)。
3. 获取端点详细信息
模式: execute、detail — 对于 help 和 browse 则跳过。
对于 execute 模式下的自然语言提示,首先检查 t
…
[已截断用于翻译]