clerk-backend-api

选项上下文

用户提示词：$ARGUMENTS

重要：每次写入请求前都必须执行的检查

每次执行 POST / PATCH / PUT / DELETE 之前，你都必须在回复中完成以下所有操作：

1. 检查 CLERK_SECRET_KEY — 确认已设置：

   echo $CLERK_SECRET_KEY | head -c 10
   

   如果为空，请停止并询问用户。没有有效的密钥时不得继续。

2. 检查 CLERK_BAPI_SCOPES — 运行：

   echo $CLERK_BAPI_SCOPES
   

   检查输出。如果缺少所需的写入权限或未包含该权限，请告知用户：“这是写入操作，而你当前的 scopes 可能不允许执行。是否使用 --admin 重新运行以绕过限制？” 不要尝试请求后再失败 — 请先询问用户。

3. 对于 DELETE 请求：明确警告该操作不可逆，并准确列出将被永久销毁的数据（用户记录、所有会话、所有成员资格、所有关联数据）。继续操作前必须获得明确确认。此警告为必需项 — 绝不可省略。

4. **对于元数据操作：**始终说明所用的元数据类型及原因（参见下文“元数据类型”部分）。

---

快速路径：常见操作（直接使用，无需获取规范）

对于以下操作，跳过获取规范，直接使用这些确切模板执行。根据用户上下文，按需替换 $CLERK_SECRET_KEY、$USER_ID、$ORG_ID、$EMAIL。

创建组织并邀请成员（分两步）

# Step 1 — Create organization
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))"

# Step 2 — Extract org ID
ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Step 3 — Invite member with role
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 等效操作（适用于使用 @clerk/nextjs 或 @clerk/backend 的 Next.js / TypeScript 项目）

import { clerkClient } from '@clerk/nextjs/server'
// OR if using @clerk/backend directly:
// import { createClerkClient } from '@clerk/backend'
// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })

// Step 1: Create organization
const org = await clerkClient.organizations.createOrganization({
  name: 'Acme Corp',
  createdBy: userId,  // required — the ID of the user creating the org
})

// Step 2: Invite member to the org
const invitation = await clerkClient.organizations.createOrganizationInvitation({
  organizationId: org.id,
  emailAddress: '[email protected]',
  role: 'org:admin',  // or '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'
// OR: import { createClerkClient } from '@clerk/backend'

await clerkClient.users.updateUser(userId, {
  publicMetadata: { plan: 'pro', onboarded: true },   // readable by client, writable server-only
  // privateMetadata: { stripeId: 'cus_xxx' },         // server-only read AND write
  // unsafeMetadata: { step: 'welcome' },              // client-writable, avoid sensitive data
})

**注意：**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'Found {len(data)} users:')
    for u in data:
        print(f'  {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
    print(json.dumps(data, indent=2))
"

删除用户（需要确认）

# ONLY run after explicit user confirmation
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'Deleted: {d}')"

---

Clerk 后端 API — 完整端点参考

基础 URL：https://api.clerk.com/v1 身份验证：每个请求都需包含 Authorization: Bearer $CLERK_SECRET_KEY。

用户

列出用户

GET /v1/users
Query params: limit (max 500, default 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 range: gt:TIMESTAMP or lt:TIMESTAMP in Unix ms)
Returns: array of User objects

获取用户

GET /v1/users/{user_id}
Returns: User object

更新用户

PATCH /v1/users/{user_id}
Body (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }

删除用户 — 不可逆

DELETE /v1/users/{user_id}
Destroys: user record, all sessions, all memberships, all associated data
Returns: { id, object, deleted: true }

始终告知用户此操作不可撤销，并在继续操作前获得确认。

组织

创建组织

POST /v1/organizations
Body: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
Returns: Organization object with { id, name, slug, ... }

列出组织

GET /v1/organizations
Query params: limit, offset, query, order_by

邀请成员

POST /v1/organizations/{organization_id}/invitations
Body: { email_address: string, role: string ("org:admin" or "org:member"), public_metadata?, private_metadata? }
Returns: OrganizationInvitation object

---

如何执行请求

**始终使用直接的 curl 命令执行请求。**使用规范提取脚本（api-specs-context.sh、extract-tags.js、extract-endpoint-detail.sh）发现端点，但使用 curl 发起实际 API 调用。

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

根据输出确定最新版本和可用标签。

**缓存：**如果在本次对话中已获取规范上下文，请勿再次获取。重用上次调用的版本和标签。

---

规则

• 对于常见操作（列出用户、创建组织、邀请、更新元数据、删除用户）：使用上面的 FAST PATH — 不要先获取规范。
• 始终忽略与 platform 相关的端点/架构。
• 执行写入请求（POST/PUT/PATCH/DELETE）前，始终先确认。
• 对于 DELETE 操作，始终警告用户此操作不可逆，并说明将丢失哪些数据（用户记录、会话、成员关系）。此警告为强制要求 — 绝不可省略。
• 对于写入操作（POST/PUT/PATCH/DELETE），尝试请求前检查 CLERK_BAPI_SCOPES。如果缺失或权限不足，应提前询问用户。不要尝试后再失败 — 执行前先询问。此检查为强制要求。
• 对于元数据操作，始终说明三种类型（public、private、unsafe），并推荐适合的类型。
• 分页：始终使用 limit + offset，并说明大型数据集的结果可能会分页。
• 所有 API 调用都使用直接的 curl 命令。

---

速率限制与注意事项

速率限制

环境	限制
生产环境	1,000 个请求 / 10 秒
开发环境	100 个请求 / 10 秒
单个邀请	100 个 / 小时
批量邀请	25 个 / 小时
组织邀请	250 个 / 小时
Frontend API 登录创建	5 个 / 10 秒
Frontend API 登录尝试	3 个 / 10 秒
每页用户列表上限	500

currentUser() 会发起真实的 API 调用，并计入速率限制。若只需获取会话声明，请使用 auth() — 它从令牌中读取，不会发起 API 调用。

元数据覆盖（而非合并）

updateUser({ publicMetadata: { role: 'admin' } }) 会替换所有 public 元数据，而不是合并。若要添加字段且不丢失现有数据：先读取，再展开，然后写入。

错误：

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' },
})

---

模式

根据 Options context 中的用户提示词确定当前模式：

模式	触发条件	行为
help	提示词为空，或仅包含 help / -h / --help	打印用法示例（步骤 0）
browse	提示词为 tags 或某个标签名称（例如 Users）	列出所有标签或某个标签的端点
execute	指定了端点（例如 GET /users）或自然语言操作（例如 "get user john_doe"）	查找端点并执行请求
detail	端点 + help / -h / --help（例如 GET /users help）	显示端点架构，不执行请求

---

你的任务

默认使用 API specs context 中的最新版本。如果用户指定了其他版本（例如 --version 2024-10-01），则使用该版本。

确定当前模式，然后按照下面适用的步骤操作。

---

0. 打印用法

模式：仅限 help — browse、execute 和 detail 模式下跳过。

将以下示例原样打印给用户：

Browse
  /clerk-backend-api tags                         — list all tags
  /clerk-backend-api Users                        — browse endpoints for the Users tag
  /clerk-backend-api Users version 2025-11-10.yml — browse using a different version

Execute
  /clerk-backend-api GET /users             — fetch all users
  /clerk-backend-api get user john_doe      — natural language works too
  /clerk-backend-api POST /invitations      — create an invitation

Inspect
  /clerk-backend-api GET /users help        — show endpoint schema without executing
  /clerk-backend-api POST /invitations -h   — view request/response details

Options
  --admin                            — bypass scope restrictions for write/delete
  --version [date], version [date]   — use a specific spec version
  --help, -h, help                   — inspect endpoint instead of executing

到此为止。

---

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 specs context 中已有的 TAGS。

用表格分享标签，并提示用户选择查询。

---

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 模式下的自然语言提示词，请先检查操作是否匹配上方的 FAST PATH 条目。如果匹配，请跳过此步骤，使用 FAST PATH 模板直接继续步骤 4。

对于其他端点，请在上下文中搜索标签，确定匹配的端点。如有需要，请获取标签端点以确定确切的路径和方法。

提取完整的端点定义：

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${path}" "${method}"

• ${path} — 例如，/users/{user_id}
• ${method} — 小写，例如，get

detail 模式： 向用户提供端点定义和架构。到此为止。

execute 模式： 继续步骤 4。

---

4. 执行请求

模式： 仅限 execute。

1. 执行上方 CRITICAL 部分中的强制检查。
2. 从规范（步骤 3）或 FAST PATH 中确定必需参数和可选参数。
3. 向用户询问尚未提供的必需路径／查询／正文参数。
4. 构建并执行直接的 curl 命令（请参阅上方的“如何执行请求”）。
5. 解析 JSON 响应并清晰地展示。提取关键字段并向用户总结。

示例 — 列出用户并解析响应：

RESPONSE=$(curl -s "https://api.clerk.com/v1/users?limit=10" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY")
echo "$RESPONSE" | python3 -c "
import sys, json
data = json.load(sys.stdin)
if isinstance(data, list):
    print(f'Found {len(data)} users:')
    for u in data:
        print(f'  {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}')
else:
    print(json.dumps(data, indent=2))
"

另请参阅

• clerk-setup - Clerk 初始安装
• clerk-orgs - 通过 API 管理组织
• clerk-webhooks - 实时事件同步