Communitygithub.com

Clerk バックエンド REST API エクスプローラ & 実行者

Clerk バックエンド REST API のタグ参照、エンドポイントスキーマ確認、認証リクエストの実行を行います。ユーザー一覧、組織管理、その他 Clerk API エンドポイント呼び出しに使用します。

Clerk バックエンド REST API エクスプローラ & 実行者 とは?

このスキルは、Clerk バックエンド REST API を探索・実行するための強力なツールです。開発者は「FAST PATH」と呼ばれる事前定義されたテンプレートを使用して、ユーザー一覧、組織作成、メンバー招待、メタデータ更新、ユーザー削除といった一般的な操作を即座に実行できます。より複雑な操作には、Clerk の OpenAPI 仕様からタグやエンドポイントを動的に取得し、curl コマンドで実際の API リクエストを実行します。このスキルは、`CLERK_SECRET_KEY` の存在確認、`CLERK_BAPI_SCOPES` による書き込み権限の検証、削除操作の不可逆性に関する警告など、重要な安全チェックを実行前に強制します。また、パブリック/プライベート/アンセーフの3種類のメタデータタイプを説明し、REST API(snake_case)と Clerk SDK(camelCase)の両方のコード例を提供するため、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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

オプションコンテキスト

ユーザープロンプト: $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 を適宜置き換えてください。

組織作成 + メンバー招待(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…

…[翻訳のため省略]

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

関連スキル