選項上下文
使用者提示:$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 等效範例(適用於使用 @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
查詢參數: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。如果遺失或不足,直接詢問使用者。不要嘗試然後失敗 — 在執行之前先詢問。此檢查是強制性的。 - 對於元資料操作,總是解釋全部三種類型(公開、私有、不安全)並建議合適的類型。
- 分頁:總是使用
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 模式中的自然語言提示,先檢查是否與快速路徑中的任何操作相符。如果是,則直接使用快速路徑範本。如果不是,則使用來自 API 規格上下文 的版本名稱:
curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${method}" "${path}"
(如果使用者提供了版本,則替換 ${version_name})。
產生結構化摘要,如果模式為 execute,則繼續執行步驟 4。