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
   

   出力を確認してください。スコープが不足している場合、または必要な書き込み権限が含まれていない場合は、ユーザーに次のように伝えてください。「これは書き込み操作であり、現在のスコープでは許可されない可能性があります。--admin を付けて再実行し、バイパスしますか？」 リクエストを試して失敗してはいけません。先に確認してください。

3. DELETE リクエストの場合： 操作が取り消し不能であることを明示し、完全に削除されるデータを正確に列挙してください（ユーザーレコード、すべてのセッション、すべてのメンバーシップ、関連するすべてのデータ）。この警告は必須です。決して省略しないでください。

4. メタデータ操作の場合： 使用するメタデータの種類と、その理由を必ず説明してください（以下の「メタデータの種類」セクションを参照）。

---

FAST PATH：一般的な操作（仕様の取得は不要。直接使用）

以下の操作では、仕様の取得を省略し、これらの正確なテンプレートを使用してすぐに実行してください。ユーザーのコンテキストに応じて、$CLERK_SECRET_KEY、$USER_ID、$ORG_ID、$EMAIL を置き換えてください。

組織を作成してメンバーを招待（2 段階）

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

ユーザーメタデータを更新

使用する種類を尋ねる前に、必ず 3 種類のメタデータを説明してください。

種類	フィールド	読み取り可能な対象	書き込み可能な対象	用途
Public	public_metadata	クライアント＋サーバー	サーバーのみ	プランの階層、ロール、フロントエンドが読み取る機能フラグ
Private	private_metadata	サーバーのみ	サーバーのみ	Stripe ID、コンプライアンスフラグ、内部識別子
Unsafe	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 Backend 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）を使用できますが、実際の API 呼び出しには curl を使用してください。

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"

レスポンスを取得した後： 内容を解析し、わかりやすく表示してください。JSON の整形には python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))" を使用します。主要なフィールド（id、メールアドレス、名前など）を抽出し、ユーザー向けに要約してください。

---

API 仕様のコンテキスト

FAST PATH 以外の操作を行う前に、次を実行して利用可能な仕様のバージョンとタグを取得してください。

bash scripts/api-specs-context.sh

出力を使用して、最新バージョンと利用可能なタグを特定してください。

キャッシュ： この会話ですでに仕様のコンテキストを取得している場合は、再取得しないでください。前回の呼び出しで取得したバージョンとタグを再利用してください。

ルール

• 一般的な操作（ユーザーの一覧表示、組織の作成、招待、メタデータの更新、ユーザーの削除）では、上記の FAST PATH を使用してください。最初に仕様を取得しないでください。
• platform に関連するエンドポイントやスキーマは、常に無視してください。
• 書き込みリクエスト（POST/PUT/PATCH/DELETE）を実行する前に、必ず確認してください。
• DELETE 操作では、その操作が取り消せないことを必ずユーザーに警告し、失われるデータ（ユーザーレコード、セッション、メンバーシップ）を伝えてください。この警告は必須です。絶対に省略しないでください。
• 書き込み操作（POST/PUT/PATCH/DELETE）では、リクエストを試みる前に CLERK_BAPI_SCOPES を確認してください。値がない、または不十分な場合は、事前にユーザーに確認してください。リクエストを試みて失敗するのではなく、実行前に確認してください。この確認は必須です。
• メタデータ操作では、public、private、unsafe の3種類すべてを必ず説明し、適切な種類を推奨してください。
• ページネーションでは、必ず limit と offset を使用し、大規模なデータセットでは結果がページ分割される可能性があることを伝えてください。
• すべての API 呼び出しには、直接 curl コマンドを使用してください。

---

レート制限と注意点

レート制限

環境	制限
本番環境	1,000 リクエスト / 10 秒
開発環境	100 リクエスト / 10 秒
個別の招待	100 / 時間
一括招待	25 / 時間
組織への招待	250 / 時間
フロントエンド API のサインイン作成	5 / 10 秒
フロントエンド API のサインイン試行	3 / 10 秒
1ページあたりのユーザー一覧の最大数	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）、または自然言語での操作（例：「ユーザー 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 - リアルタイムのイベント同期