clerk-backend-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Options context

选项上下文

User Prompt: $ARGUMENTS

用户提示：$ARGUMENTS

CRITICAL: Mandatory checks before EVERY write request

重要提示：每次写入请求前的强制检查

Before ANY POST / PATCH / PUT / DELETE, you MUST do ALL of the following in your response:

Check CLERK_SECRET_KEY — verify it is set:
bash
```
echo $CLERK_SECRET_KEY | head -c 10
```
If empty, stop and ask the user. Do not proceed without a valid key.
Check CLERK_BAPI_SCOPES — run:
bash
```
echo $CLERK_BAPI_SCOPES
```
Inspect the output. If scopes are missing or do not include the required write permission, tell the user: "This is a write operation and your current scopes may not allow it. Rerun with --admin to bypass?" Do NOT attempt the request and fail — ask first.
For DELETE requests: warn explicitly that the action is IRREVERSIBLE and list exactly what data will be permanently destroyed (user record, all sessions, all memberships, all associated data). Require explicit confirmation before proceeding. This warning is MANDATORY — never skip it.
For metadata operations: always explain which metadata type is being used and why (see Metadata types section below).

在执行任何POST / PATCH / PUT / DELETE请求前，你必须在响应中完成以下所有操作：

检查CLERK_SECRET_KEY — 验证其已设置：
bash
```
echo $CLERK_SECRET_KEY | head -c 10
```
如果为空，请停止操作并询问用户。没有有效密钥请勿继续。
检查CLERK_BAPI_SCOPES — 运行：
bash
```
echo $CLERK_BAPI_SCOPES
```
检查输出内容。如果权限范围缺失或不包含所需的写入权限，请告知用户："这是写入操作，你当前的权限范围可能不允许执行。是否使用--admin参数绕过限制？" 请勿尝试执行请求导致失败 — 先询问用户。
对于DELETE请求： 明确警告该操作是不可撤销的，并列出将被永久删除的具体数据（用户记录、所有会话、所有成员身份、所有关联数据）。执行前必须获得用户的明确确认。此警告为强制要求 — 绝不能跳过。
对于元数据操作： 始终说明正在使用的元数据类型及其原因（见下方元数据类型部分）。

FAST PATH: Common operations (use directly, no spec fetching needed)

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

For the operations below, skip spec fetching and execute immediately using these exact templates. Substitute

$CLERK_SECRET_KEY

$USER_ID

$ORG_ID

$EMAIL

as needed from the user's context.

对于以下操作，跳过规格获取步骤，直接使用以下精确模板执行。根据用户上下文替换

$CLERK_SECRET_KEY

、

$USER_ID

、

$ORG_ID

、

$EMAIL

等变量。

Create organization + invite member (two-step)

创建组织 + 邀请成员（两步操作）

bash

undefined

bash

undefined

Step 1 — Create organization

步骤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))"

Step 2 — Extract org ID

步骤2 — 提取组织ID

ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

Step 3 — Invite member with role

步骤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": "user@example.com", "role": "org:admin"}"
| python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))"


**Roles:** use `"org:admin"` or `"org:member"` (always prefix with `org:`).


**角色：** 使用`"org:admin"`或`"org:member"`（必须以`org:`为前缀）。

SDK equivalent (for Next.js / TypeScript projects with

@clerk/nextjs

@clerk/backend

)

SDK等效代码（适用于使用

@clerk/nextjs

或

@clerk/backend

的Next.js / TypeScript项目）

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: 'user@example.com',
  role: 'org:admin',  // or 'org:member'
})

typescript

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: 'user@example.com',
  role: 'org:admin',  // 或 'org:member'
})

Update user metadata

更新用户元数据

Always explain the three metadata types before asking which to use:

Type	Field	Readable by	Writable by	Use for
Public	`public_metadata`	Client + Server	Server only	Plan tier, roles, feature flags the frontend reads
Private	`private_metadata`	Server only	Server only	Stripe IDs, compliance flags, internal identifiers
Unsafe	`unsafe_metadata`	Client + Server	Client + Server	Ephemeral UI state, onboarding steps (client-writable — avoid sensitive data)

For
plan: 'pro'
and
onboarded: true
— use
public_metadata
(frontend-readable, server-writable):

bash

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 equivalent:

typescript

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

Note: REST API uses

snake_case

(

public_metadata

). SDK uses

camelCase

(

publicMetadata

在询问使用哪种类型前，始终先说明三种元数据类型：

类型	字段	可读方	可写方	用途
公开	`public_metadata`	客户端 + 服务端	仅服务端	前端可读的套餐层级、角色、功能标志
私有	`private_metadata`	仅服务端	仅服务端	Stripe ID、合规标志、内部标识符
不安全	`unsafe_metadata`	客户端 + 服务端	客户端 + 服务端	临时UI状态、引导步骤（客户端可写 — 避免存储敏感数据）

对于
plan: 'pro'
和
onboarded: true
— 使用
public_metadata
（前端可读，仅服务端可写）：

bash

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等效代码：

typescript

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

）。

List users (last 7 days)

列出用户（最近7天）

bash

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))
"

bash

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))
"

Delete user (confirm required)

删除用户（需要确认）

bash

undefined

bash

undefined

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

---

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 Backend API — Full Endpoint Reference

Clerk后端API — 完整端点参考

Base URL:

https://api.clerk.com/v1

Auth:

Authorization: Bearer $CLERK_SECRET_KEY

on every request.

基础URL：

https://api.clerk.com/v1

认证：每个请求都需携带

Authorization: Bearer $CLERK_SECRET_KEY

。

Users

用户

List users

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 user

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

Update user

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

Delete user — IRREVERSIBLE

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

Always warn the user this is permanent and confirm before proceeding.

列出用户

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 }

始终警告用户此操作是永久性的，并在执行前获得确认。

Organizations

组织

Create organization

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, ... }

List organizations

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

Invite member

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

创建组织

POST /v1/organizations
请求体：{ name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }
返回值：包含{ id, name, slug, ... }的Organization对象

列出组织

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对象

How to execute requests

如何执行请求

ALWAYS execute requests with direct
curl
commands. Use the spec-extraction scripts (

api-specs-context.sh

extract-tags.js

extract-endpoint-detail.sh

) to discover endpoints, but make actual API calls with

curl

. Do NOT use

scripts/execute-request.sh

— it's a local dev helper, not for agent use.

Template for GET requests:

bash

curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

Template for POST/PATCH requests:

bash

curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '${BODY_JSON}'

Template for DELETE requests:

bash

curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

After getting the response: Parse and display it clearly. Use

python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))"

to pretty-print JSON. Extract key fields (id, email, name, etc.) and summarize them for the user.

始终使用直接的
curl
命令执行请求。使用规格提取脚本（

api-specs-context.sh

、

extract-tags.js

、

extract-endpoint-detail.sh

）发现端点，但实际API调用必须使用

curl

。请勿使用

scripts/execute-request.sh

— 这是本地开发辅助工具，不适合Agent使用。

GET请求模板：

bash

curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \
  -H "Authorization: Bearer $CLERK_SECRET_KEY"

POST/PATCH请求模板：

bash

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请求模板：

bash

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、邮箱、名称等）并为用户总结。

API specs context

API规格上下文

Before doing anything outside the FAST PATH, fetch the available spec versions and tags by running:

bash

bash scripts/api-specs-context.sh

Use the output to determine the latest version and available tags.

Caching: If you already fetched the spec context earlier in this conversation, do NOT fetch it again. Reuse the version and tags from the previous call.

在执行快速路径之外的任何操作前，通过运行以下命令获取可用的规格版本和标签：

bash

bash scripts/api-specs-context.sh

使用输出内容确定最新版本和可用标签。

缓存： 如果在此对话中之前已获取过规格上下文，请勿再次获取。复用之前调用得到的版本和标签。

Rules

规则

For common operations (list users, create org, invite, update metadata, delete user): use the FAST PATH above — do NOT fetch specs first.
Always disregard endpoints/schemas related to
```
platform
```
.
Always confirm before performing write requests (POST/PUT/PATCH/DELETE).
For DELETE operations, always warn the user that the action is irreversible and mention what data will be lost (user record, sessions, memberships). This warning is MANDATORY — never skip it.
For write operations (POST/PUT/PATCH/DELETE), check
```
CLERK_BAPI_SCOPES
```
before attempting the request. If missing or insufficient, ask the user upfront. Do NOT attempt and fail — ask before executing. This check is MANDATORY.
For metadata operations, always explain all three types (public, private, unsafe) and recommend the appropriate one.
Pagination: always use
```
limit
```
+
```
offset
```
and mention that results may be paginated for large datasets.
Use direct curl commands for all API calls — never use
```
scripts/execute-request.sh
```
.

对于常见操作（列出用户、创建组织、邀请成员、更新元数据、删除用户）：使用上述快速路径 — 请勿先获取规格。
始终忽略与
```
platform
```
相关的端点/架构。
执行写入请求（POST/PUT/PATCH/DELETE）前始终确认。
对于DELETE操作，始终警告用户该操作不可撤销，并说明将丢失的数据（用户记录、会话、成员身份）。此警告为强制要求 — 绝不能跳过。
对于写入操作（POST/PUT/PATCH/DELETE），执行前检查
```
CLERK_BAPI_SCOPES
```
。如果权限缺失或不足，提前询问用户。请勿尝试执行导致失败 — 执行前先询问。此检查为强制要求。
对于元数据操作，始终说明所有三种类型（公开、私有、不安全）并推荐合适的类型。
分页：始终使用
```
limit
```
+
```
offset
```
，并提及对于大型数据集结果可能会分页。
所有API调用使用直接的curl命令 — 绝不使用
```
scripts/execute-request.sh
```
。

Rate Limits & Gotchas

速率限制与注意事项

Rate Limits

速率限制

Environment	Limit
Production	1,000 requests / 10 seconds
Development	100 requests / 10 seconds
Single invitations	100 / hour
Bulk invitations	25 / hour
Org invitations	250 / hour
Frontend API sign-in creation	5 / 10 seconds
Frontend API sign-in attempts	3 / 10 seconds
List users max per page	500

currentUser()

makes a real API call that counts against rate limits. Use

auth()

for just the session claims — it reads from the token without an API call.

环境	限制
生产环境	10秒内1000次请求
开发环境	10秒内100次请求
单次邀请	每小时100次
批量邀请	每小时25次
组织邀请	每小时250次
前端API登录创建	10秒内5次
前端API登录尝试	10秒内3次
单页列出用户最大数量	500

currentUser()

会发起真实的API调用，计入速率限制。使用

auth()

仅获取会话声明 — 它从令牌读取数据，无需API调用。

Metadata Overwrites (Not Merges)

元数据覆盖（非合并）

updateUser({ publicMetadata: { role: 'admin' } })

REPLACES all public metadata, not merges. To add a field without losing existing data: read first, spread, then write.

Wrong:

typescript

await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })

This DELETES all other

publicMetadata

fields.

Right:

typescript

const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
  publicMetadata: { ...user.publicMetadata, newField: 'value' },
})

updateUser({ publicMetadata: { role: 'admin' } })

会替换所有公开元数据，而非合并。要添加字段且不丢失现有数据：先读取，再扩展，最后写入。

错误示例：

typescript

await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })

此操作会删除所有其他

publicMetadata

字段。

正确示例：

typescript

const user = await clerkClient.users.getUser(userId)
await clerkClient.users.updateUser(userId, {
  publicMetadata: { ...user.publicMetadata, newField: 'value' },
})

Modes

模式

Determine the active mode based on the user prompt in Options context:

Mode	Trigger	Behavior
`help`	Prompt is empty, or contains only `help` / `-h` / `--help`	Print usage examples (step 0)
`browse`	Prompt is `tags` , or a tag name (e.g. `Users` )	List all tags or endpoints for a tag
`execute`	Specific endpoint (e.g. `GET /users` ) or natural language action (e.g. "get user john_doe")	Look up endpoint, execute request
`detail`	Endpoint + `help` / `-h` / `--help` (e.g. `GET /users help` )	Show endpoint schema, don't execute

根据选项上下文中的用户提示确定当前模式：

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

Your Task

你的任务

Use the LATEST VERSION from API specs context by default. If the user specifies a different version (e.g.

--version 2024-10-01

), use that version instead.

Determine the active mode, then follow the applicable steps below.

默认使用API规格上下文中的最新版本。如果用户指定了其他版本（例如

--version 2024-10-01

），则使用该版本。

确定当前模式，然后遵循以下适用步骤。

0. Print usage

0. 打印使用说明

Modes:

help

only — Skip for

browse

execute

, and

detail

Print the following examples to the user verbatim:

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

Stop here.

模式： 仅

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. Fetch tags

1. 获取标签

Modes:

browse

(when prompt is

tags

or no tag specified) — Skip for

help

execute

, and

detail

If using a non-latest version, fetch tags for that version:

bash

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js

Otherwise, use the TAGS already in API specs context.

Share tags in a table and prompt the user to select a query.

模式：

browse

模式（当提示为

tags

或未指定标签时） —

help

、

execute

和

detail

模式跳过此步骤。

如果使用非最新版本，获取该版本的标签：

bash

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js

否则，使用API规格上下文中已有的标签。

以表格形式展示标签，并提示用户选择查询内容。

2. Fetch tag endpoints

2. 获取标签端点

Modes:

browse

(when a tag name is provided) — Skip for

help

execute

, and

detail

Fetch all endpoints for the identified tag:

bash

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"

Share the results (endpoints, schemas, parameters) with the user.

模式：

browse

模式（当提供标签名称时） —

help

、

execute

和

detail

模式跳过此步骤。

获取指定标签下的所有端点：

bash

curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"

向用户展示结果（端点、架构、参数）。

3. Fetch endpoint detail

3. 获取端点详情

Modes:

execute

detail

— Skip for

help

and

browse

For natural language prompts in

execute

mode, first check if the operation matches a FAST PATH entry above. If it does, skip this step and proceed directly to step 4 using the FAST PATH template.

For other endpoints, identify the matching endpoint by searching the tags in context. Fetch tag endpoints if needed to resolve the exact path and method.

Extract the full endpoint definition:

bash

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

```
${path}
```
— e.g.
```
/users/{user_id}
```
```
${method}
```
— lowercase, e.g.
```
get
```

detail
mode: Share the endpoint definition and schemas with the user. Stop here.

execute
mode: Continue to step 4.

模式：

execute

、

detail

模式 —

help

和

browse

模式跳过此步骤。

对于

execute

模式下的自然语言提示，首先检查操作是否匹配上述快速路径条目。如果匹配，跳过此步骤，直接使用快速路径模板进入步骤4。

对于其他端点，通过上下文中的标签查找匹配的端点。如有需要，获取标签端点以确定精确路径和方法。

提取完整的端点定义：

bash

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 request

4. 执行请求

Modes:

execute

only.

Run the mandatory checks from the CRITICAL section above.
Identify required and optional parameters from the spec (step 3) or FAST PATH.
Ask the user for any required path/query/body parameters that weren't provided.
Build and execute a direct curl command (see How to execute requests above). Do NOT use
```
scripts/execute-request.sh
```
.
Parse the JSON response and display it clearly. Extract and summarize key fields for the user.

Example — list users and parse response:

bash

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))
"

模式： 仅

execute

模式。

运行上述重要提示部分中的强制检查。
从规格（步骤3）或快速路径中识别必填和可选参数。
向用户询问任何未提供的必填路径/查询/请求体参数。
构建并执行直接的curl命令（见上方如何执行请求部分）。请勿使用
```
scripts/execute-request.sh
```
。
解析JSON响应并清晰展示。提取关键字段并为用户总结。

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

bash

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
```
- Initial Clerk install
```
clerk-orgs
```
- Manage organizations via API
```
clerk-webhooks
```
- Real-time event sync

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

clerk-backend-api

Original

Translation

Options context

选项上下文

CRITICAL: Mandatory checks before EVERY write request

重要提示：每次写入请求前的强制检查

FAST PATH: Common operations (use directly, no spec fetching needed)

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

Create organization + invite member (two-step)

创建组织 + 邀请成员（两步操作）

Step 1 — Create organization

步骤1 — 创建组织

Step 2 — Extract org ID

步骤2 — 提取组织ID

Step 3 — Invite member with role

步骤3 — 邀请成员并指定角色

SDK equivalent (for Next.js / TypeScript projects with @clerk/nextjs or @clerk/backend)

SDK等效代码（适用于使用@clerk/nextjs或@clerk/backend的Next.js / TypeScript项目）

Update user metadata

更新用户元数据

List users (last 7 days)

列出用户（最近7天）

Delete user (confirm required)

删除用户（需要确认）

ONLY run after explicit user confirmation

仅在获得用户明确确认后运行

Clerk Backend API — Full Endpoint Reference

Clerk后端API — 完整端点参考

Users

用户

Organizations

组织

How to execute requests

如何执行请求

API specs context

API规格上下文

Rules

规则

Rate Limits & Gotchas

速率限制与注意事项

Rate Limits

速率限制

Metadata Overwrites (Not Merges)

元数据覆盖（非合并）

Modes

模式

Your Task

你的任务

0. Print usage

0. 打印使用说明

1. Fetch tags

1. 获取标签

2. Fetch tag endpoints

2. 获取标签端点

3. Fetch endpoint detail

3. 获取端点详情

4. Execute request

4. 执行请求

See Also

另请参阅

SDK equivalent (for Next.js / TypeScript projects with
`@clerk/nextjs`
or
`@clerk/backend`
)

SDK等效代码（适用于使用
`@clerk/nextjs`
或
`@clerk/backend`
的Next.js / TypeScript项目）