オプションコンテキスト
ユーザープロンプト: $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 を適宜置き換えてください。
組織作成 + メンバー招待(2ステップ)
# ステップ 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'
// または @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'
})
ユーザーメタデータの更新
どのメタデータタイプを使用するかユーザーに尋ねる前に、3つのタイプを常に説明してください:
| タイプ | フィールド | 読み取り可能 | 書き込み可能 | 用途 |
|---|---|---|---|---|
| パブリック | 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'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))
"
ユーザー削除(確認必須)
# ユーザーからの明示的な確認後にのみ実行
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? }
戻り値: { 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 オブジェクト
リクエストの実行方法
常に直接 curl コマンドでリクエストを実行してください。 エンドポイントの発見には仕様抽出スクリプト(api-specs-context.sh、extract-tags.js、extract-endpoint-detail.sh)を使用しますが、実際の API 呼び出しは curl で行います。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を確認してください。不足しているか不十分な場合は、事前にユーザーに確認を取ってください。試行して失敗させないでください — 実行前に確認してください。このチェックは必須です。 - メタデータ操作の場合、常に3つのタイプすべて(パブリック、プライベート、アンセーフ)を説明し、適切なものを推奨してください。
- ページネーション: 常に
limit+offsetを使用し、大規模なデータセットでは結果がページ分割される可能性があることを言及してください。 - すべての API 呼び出しには直接 curl コマンドを使用してください —
scripts/execute-request.shは使用しないでください。
レート制限と注意点
レート制限
| 環境 | 制限 |
|---|---|
| 本番 | 1,000 リクエスト / 10 秒 |
| 開発 | 100 リクエスト / 10 秒 |
| 単一招待 | 100 / 時間 |
| 一括招待 | 25 / 時間 |
| 組織招待 | 250 / 時間 |
| フロントエンド API サインイン作成 | 5 / 10 秒 |
| フロントエンド API サインイン試行 | 3 / 10 秒 |
| ユーザー一覧の1ページあたりの最大数 | 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 仕様コンテキスト に既にある 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 モードで自然言語プロンプトの場合、まず t…
…[翻訳のため省略]