Communitygithub.com

Clerk 后端 REST API 探索器与执行器

浏览标签、检查端点架构并执行经过身份验证的请求。用于列出用户、管理组织或调用任何 Clerk API 端点。

Clerk 后端 REST API 探索器与执行器 是什么?

该技能提供了一个强大的界面,用于探索和执行 Clerk 后端 REST API。它允许开发者快速浏览 API 标签和端点,检查请求和响应模式,并直接执行经过身份验证的 API 请求。该技能支持 `browse`、`execute` 和 `detail` 等多种模式,可以灵活地交互 API。它通过处理 API 密钥和权限范围检查、对写操作(尤其是 DELETE 请求)进行不可逆操作警告以及对元数据操作进行类型解释,强制实施安全最佳实践。该技能适用于 Claude Code 等 AI 代理平台,有助于简化用户管理、组织操作和其他常见 Clerk 工作流,如创建组织、邀请成员和更新用户元数据。它提供了一个“快速路径”用于常见操作以避免不必要的规范获取,并且可以通过 `curl` 命令或通过 SDK 等效项(适用于 Next.js/TypeScript 项目)直接使用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-backend-api

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

选项上下文

用户提示: $ARGUMENTS

关键: 每次写请求前的强制性检查

在任何 POST / PATCH / PUT / DELETE 之前,您必须在响应中完成以下所有检查:

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

    echo $CLERK_SECRET_KEY | head -c 10
    

    如果为空,请停止并询问用户。没有有效密钥则无法继续。

  2. 检查 CLERK_BAPI_SCOPES — 运行:

    echo $CLERK_BAPI_SCOPES
    

    检查输出。如果缺少作用域或不包含所需的写权限,请告知用户: "这是一个写操作,您当前的作用域可能不允许。使用 --admin 重新运行以绕过?" 不要尝试请求并失败 — 先询问。

  3. 对于 DELETE 请求: 明确警告该操作是不可逆的,并准确列出将被永久销毁的数据(用户记录、所有会话、所有成员资格、所有关联数据)。要求用户明确确认后才能继续。此警告是强制性的 — 绝不能跳过。

  4. 对于元数据操作: 始终解释正在使用的元数据类型及其原因(参见下面的元数据类型部分)。


快速路径: 常见操作(直接使用,无需获取规范)

对于以下操作,跳过规范获取,直接使用这些确切的模板。根据用户上下文替换 $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

…

[已截断用于翻译]

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

相关技能