> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys.md). # API キーの管理 ## 概要 Roboflow API を使用して、ワークスペースの API キーをプログラムから管理できます。新しいキーの作成、既存キーの一覧表示と確認、名前変更、メタデータの付与、無効化、保護、失効が可能です。 これは [`roboflow api-key` CLI](#cli) および [Roboflow MCP サーバー](https://docs.roboflow.com/agents/agents/mcp-server)と同じインターフェースなので、自動化エージェントはダッシュボードから人がコピペすることなく、アプリケーションに必要なキーをプロビジョニングできます。 {% hint style="info" %} **シークレットは一度しか書き込めません。** 完全なキー値が返されるのは **のみ** キーを作成（またはロール）したときです。その他のすべてのエンドポイントは、シークレットではない `keyId` ハンドルと短い `接頭辞` を識別用に返します - キーそのものは返しません。値は安全に保存してください（例: `.gitignore`化 `.env`）を作成時に。 {% endhint %} ## HTTP API ### 認証 API キーを `api_key` クエリパラメータとして、または `Authorization: Bearer ` ヘッダーとして送信してください。他の REST エンドポイントと同じです（参照 [REST API で認証する](/reference/ja/purattofmu/rest-api/authenticate-with-the-rest-api.md)）。使用するキーは、パス内のワークスペースに属している必要があります。 これらのエンドポイントは Roboflow の [ロールと権限](/reference/ja/ren-zheng/authentication/scoped-api-keys.md)を尊重します。呼び出し元が **ユーザーとして動作する OAuth トークン**である場合、関連する RBAC アクション（`create_api_key`, `update_api_key`, `revoke_api_key`, `get_api_key`, `view_workspace_api_keys`）はデフォルトでワークスペースの **所有者/管理者**になります。スコープ付きキー（またはユーザーとして動作する OAuth トークン）での要求は、呼び出し元自身がすでに持っている能力しか作成・付与できません。参照 [権限のサブセット規則](#privilege-subset-rules). 呼び出し元が **スコープ付き（非 OAuth）プライベートキー**である場合、さらに [スコープ](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) が必要です。エンドポイントに一致するもの: | エンドポイント | 必須スコープ | | --------------------- | ---------------- | | `GET` list / `GET` 1件 | `api-key:read` | | `POST` 作成 | `api-key:create` | | `PATCH` 更新 | `api-key:update` | | `DELETE` 失効 | `api-key:revoke` | | `GET` 公開可能な | `workspace:read` | スコープなし（フルアクセス）のプライベートキーであれば、これらはすべて満たします。必要なスコープが欠けているキーは、ルートが存在しないものとして扱われます - 参照 [エラー](#errors). {% hint style="warning" %} 1つの [公開可能キー](#the-publishable-key) (`rf_`）は **受け付けられません** これらの管理エンドポイントの認証には使用できません。プライベートキーで認証してください。 {% endhint %} ### API キー一覧 `GET` `/:workspace/api-keys` ワークスペースの API キー（マスク済み）を一覧表示し、ワークスペースの公開可能キーを返します。 **クエリ**
名前型説明必須
api_keystringワークスペース用のプライベート API キー。true
includeDisabledboolean無効化されたキーも結果に含める（デフォルト false).false
includeFoldersbooleanフォルダスコープ付きキーのフォルダ詳細を展開する（デフォルト false).false
**リクエスト例** ```bash curl --location 'https://api.roboflow.com//api-keys?api_key=$ROBOFLOW_API_KEY' ``` **レスポンス** {% tabs %} {% tab title="200" %} ```json { "apiKeys": [ { "keyId": "9f8c1a2b3d4e5f60", "name": "production-server", "prefix": "abcd", "scopes": ["model:infer"], "folderIds": [], "default": false, "protected": true, "disabled": false, "created_on": "2026-06-19T18:24:01.000Z", "created_by": "user_abc123", "custom_metadata": { "env": "prod" } } ], "publishableKey": "rf_" } ``` {% endtab %} {% endtabs %} 注記: * `keyId` 他のエンドポイントでキーを指定するために使う、安定した非シークレットのハンドルです。 * `スコープ` は `null` スコープなし（フルアクセス）キーの場合、または [スコープ文字列の配列](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) スコープ付きキーの場合。 * `created_on` （ISO 8601）と `created_by` は、その値が記録されているキーにのみ含まれます。これらの属性が追跡される前に作成された古いキーには含まれません。 * `created_by` は **不透明な** キーを作成した人を示す識別子です - ユーザー ID、 `api_key:` （別の API キーによって作成された場合）、または `SYSTEM` （自動プロセスによって作成された場合）。表示/監査用の文字列として扱い、解析しないでください。 * `custom_metadata` が含まれるのは **のみ** ワークスペースのプランに Advanced API Keys が含まれている場合です。この機能がない場合、（メタデータを持つキーでも）フィールドは完全に存在しません。 ### 単一の API キーを取得 `GET` `/:workspace/api-keys/:keyId` その `keyId` ハンドル。 **リクエスト例** ```bash curl --location 'https://api.roboflow.com//api-keys/?api_key=$ROBOFLOW_API_KEY' ``` **レスポンス** {% tabs %} {% tab title="200" %} ```json { "apiKey": { "keyId": "9f8c1a2b3d4e5f60", "name": "production-server", "prefix": "abcd", "scopes": ["model:infer"], "folderIds": [], "default": false, "protected": true, "disabled": false, "created_on": "2026-06-19T18:24:01.000Z", "created_by": "user_abc123" } } ``` {% endtab %} {% tab title="404" %} そのキーに一致する `keyId` ものはワークスペースに存在しません（または失効済みです）、 **または** 認証情報に `api-key:read` スコープがないか、属していないワークスペースを対象にしています。権限エラーではオブジェクト形式のエラー `{"error": {"message", "type", "hint"}}`；未知の `keyId` は `{"error": "string"}`。参照 [エラー](#errors). {% endtab %} {% endtabs %} ### API キーを作成 `POST` `/:workspace/api-keys` 新しい API キーを作成します。シークレット値が **1回** の中で `key` フィールドで返されます。 **ヘッダー** | 名前 | 値 | | ------------ | ------------------ | | Content-Type | `application/json` | **本文**
名前型説明必須
namestringキーの分かりやすいラベル。false
スコープArray<string> | nullキーをこれらに制限します スコープ。以下の 3 つの状態を参照してください。 Advanced API Keys が必要です。false
folderIdsArray<string>キーをこれらのプロジェクトフォルダに制限します。 Advanced API Keys が必要です。false
custom_metadataMap<string, string>最大 20 個の key/value ペア（キーは 100 文字以下、値は 500 文字以下）。 Advanced API Keys が必要です。false
protectedbooleanキーを protected 状態で作成します。false
{% hint style="info" %} **`スコープ` 作成時:** * **省略** - 新しいキーは **呼び出し元の認証情報自身のスコープを継承します** （「自分と同じようなキーを作成する」）。これはプランに依存しません。フルアクセスキーはフルアクセスキーを作成し、スコープ付きキーは同じスコープのキーを作成し、フォルダも同じ方法で継承されます。スクリプトが `スコープ` を省略しても、ワークスペースに Advanced API Keys 機能があるかどうかに関係なく同じように動作します。 * **`null`** - 明示的な **フルアクセス** （スコープなし）キー。呼び出し元自身がフルアクセスである必要があります（スコープ付き呼び出し元は拒否されます - 参照 [サブセット規則](#privilege-subset-rules)). * **`[]`** （空配列） - **能力のない**有効なキーですが、; スコープ付きルートはすべて拒否します。後でスコープを付与するためのプレースホルダーとして便利です。 * **`["model:infer", …]`** - **スコープ付き** にする [セクション名](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) たとえば `model` そのセクションのすべてのスコープを付与します）。 * **`["role:reviewer", …]`** - [**ロールプリセット**](/reference/ja/ren-zheng/authentication/scoped-api-keys.md): 作成時にそのロールのスコープへ展開されます。組み込みロール（`ラベラー`, `レビュアー`, `オーナー`）またはカスタムロール名を使用してください。 `role:owner` はフルアクセスを意味します。明示的なスコープと組み合わせ可能です。 明示的な `スコープ` **配列** (`[]`、リスト、または `role:` プリセット）を指定するには、 `folderIds`、または `custom_metadata` Advanced API Keys **プラン機能が必要です（それ以外の場合** ）。 `403`を省略する `スコープ` （継承）と `null` （フル）は必要ありません。したがって、デフォルトはすべてのプランで機能します。 {% endhint %} **リクエスト例** ```bash curl --location 'https://api.roboflow.com//api-keys?api_key=$ROBOFLOW_API_KEY' \\ --header 'Content-Type: application/json' \\ --data '{ "name": "production-server", "scopes": ["model:infer"] }' ``` **レスポンス** {% tabs %} {% tab title="201" %} ```json { "keyId": "9f8c1a2b3d4e5f60", "key": "AbCdEf0123456789xyz", "name": "production-server", "scopes": ["model:infer"], "folderIds": [], "protected": false, "publishableKey": "rf_" } ``` {% endtab %} {% tab title="403" %} 呼び出し元はキーを作成できますが、自分が持つ権限を超えるスコープ/フォルダの付与を要求したか、ワークスペースのプランに要求された高度機能が含まれていません。本文: `{"error": "string"}`. {% endtab %} {% tab title="404" %} 認証情報に `api-key:create` スコープがないか、属していないワークスペースを対象にしています。本文: `{"error": {"message", "type", "hint"}}`。参照 [エラー](#errors). {% endtab %} {% endtabs %} {% hint style="danger" %} この `key` フィールドがシークレット値であり、このレスポンスで表示されます。今すぐ保存してください。再取得はできません。 **のみ** 今すぐ保存してください。再取得はできません。 {% endhint %} ### API キーを更新 `PATCH` `/:workspace/api-keys/:keyId` キーの名前、スコープ、またはメタデータを更新します。保護したり、有効化/無効化したりできます。 **ヘッダー** | 名前 | 値 | | ------------ | ------------------ | | Content-Type | `application/json` | **本文** （変更したいフィールドだけを送信してください）
名前型説明必須
namestring新しい表示名。false
スコープArray<string> | null新しい スコープ （呼び出し元のサブセット）。以下の 3 つの状態を参照してください。 Advanced API Keys が必要です。false
custom_metadataMap<string, string>キーのメタデータを置き換えます。 Advanced API Keys が必要です。false
protectedtrueキーを保護します。API は 保護を解除できません - 下記参照。false
無効化boolean無効化（true）または再有効化（false）します。 Advanced API Keys が必要です。false
{% hint style="info" %} **の 3 つの状態 `スコープ`** （PATCH の意味は create と少し異なり、フィールドを省略すると変更されません）： * **省略** - キーの既存のスコープは **変更されません**. * **`null`** - キーは **フルアクセス** （スコープなし）になります。これを付与するには、呼び出し元自身がフルアクセスを持っている必要があります。 * **`[]`** （空配列） - キーは有効な認証情報のままですが、 **能力のない**. * **`["model:infer", …]`** - **置き換えます** キーのスコープをこのセットだけに置き換えます（ [セクション名](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) はそのセクションのすべてのスコープに展開されます）。 送信すると `スコープ` (**を含めると `[]` または `null`**), `custom_metadata`、または `無効化` Advanced API Keys **プラン機能が必要です（それ以外の場合** プラン機能。 {% endhint %} **リクエスト例** ```bash curl --location --request PATCH 'https://api.roboflow.com//api-keys/?api_key=$ROBOFLOW_API_KEY' \\ --header 'Content-Type: application/json' \\ --data '{ "name": "renamed-key" }' ``` **レスポンス** {% tabs %} {% tab title="200" %} ```json { "apiKey": { "keyId": "9f8c1a2b3d4e5f60", "name": "renamed-key", "prefix": "abcd", "scopes": ["model:infer"], "folderIds": [], "default": false, "protected": false, "disabled": false } } ``` {% endtab %} {% tab title="403" %} 次の場合に返されます `"protected": false` （API はキーの保護を解除できません）、または呼び出し元が付与できないスコープを要求した場合。本文: `{"error": "string"}`. {% endtab %} {% tab title="404" %} そのキーに一致する `keyId` ワークスペース内で（本文: `{"error": "string"}`), **または** 認証情報に `api-key:update` スコープ / ワークスペース外を対象にしている場合（本文: `{"error": {"message", "type", "hint"}}`）。参照 [エラー](#errors). {% endtab %} {% tab title="409" %} 現在 [protected](#protecting-a-key). {% endtab %} {% endtabs %} ### API キーを失効 `DELETE` `/:workspace/api-keys/:keyId` キーを失効させます（永続的に無効化します）。それを使用している既存アプリケーションは直ちに認証に失敗します。 **リクエスト例** ```bash curl --location --request DELETE 'https://api.roboflow.com//api-keys/?api_key=$ROBOFLOW_API_KEY' ``` **レスポンス** {% tabs %} {% tab title="200" %} ```json { "status": "revoked", "keyId": "9f8c1a2b3d4e5f60" } ``` {% endtab %} {% tab title="409" %} キーは [protected](#protecting-a-key)。まず Roboflow ダッシュボードで保護を解除してください。 {% endtab %} {% endtabs %} ### キーの保護 1つの **protected** 保護が解除されるまで、キーは API、CLI、MCP サーバー、 *または* ダッシュボードのいずれからも無効化または失効できません。これにより、自動化エージェントが誤って本番キーを停止してしまうのを防げます。 * **保護:** `PATCH` で `{ "protected": true }`. * **保護解除:** できます **のみ** ダッシュボードで [行えます](https://app.roboflow.com/settings/api)。API/CLI/MCP は意図的にキーの保護を解除できないため、侵害されたり暴走したエージェントが安全装置を外してから一気にキーを失効させることを防げます。 ### 公開可能キー すべてのワークスペースには **公開可能キー** という形式の `rf_`があります。 * **シークレットではない** - クライアント側 / ブラウザーコードに埋め込んでも安全です（例: [inferencejs](https://docs.roboflow.com/deployment/self-hosted/sdks/web-browser)). * **推論 + モデルダウンロードのみ** - データの管理、トレーニング、キー管理はできません。 * **永続的** - ワークスペース ID から導出されるため、作成、ローテーション、失効はできません。 から読み取ってください `publishableKey` フィールドを一覧/作成レスポンスから、または直接: `GET` `/:workspace/api-keys/publishable` ```bash curl --location 'https://api.roboflow.com//api-keys/publishable?api_key=$ROBOFLOW_API_KEY' # { "publishableKey": "rf_" } ``` ブラウザー/エッジ推論には公開可能キーを、サーバーサイド作業にはスコープ付きプライベートキーを使用してください。公開可能キーを持つ人はそのワークスペースのモデルに対して推論を実行し、（および）ダウンロードできることに注意してください。これは「公開可能」資格情報の意図されたトレードオフです。 ### 権限のサブセット規則 権限昇格を防ぐため、新しく作成または更新されたキーは、それを作成する認証情報より多くの能力を持つことはできません。 * これらのエンドポイントを **スコープ付きプライベートキー**で呼び出すと、新しいキーの `スコープ` は呼び出し元キーのスコープのサブセットでなければならず、その `folderIds` は呼び出し元キーのフォルダのサブセットでなければなりません。スコープなし（フルアクセス）キーは何でも付与できます。 * それらを **ユーザーとして動作する OAuth トークン**OAuth トークン で呼び出すと、要求されたスコープはそのユーザーのロールでも追加検証されます - ロールが許可する能力しか付与できません。 `403`. ### エラー | ステータス | 意味 | エラー形式 | | ----- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `400` | 不正なリクエスト本文（例: 不明なスコープ、壊れたメタデータ）。 | `{"error": "string"}` | | `403` | 呼び出し元はルートの認可を受けていますが、 **持っている範囲を超える能力を付与する** （呼び出し元を超えるスコープ/フォルダ）、プランに Advanced API Keys が含まれていない、または API 経由で保護解除を試みた場合。 | `{"error": "string"}` | | `404` | その `keyId` がワークスペースに存在しないか、 **または** 認証情報にルートが必要とするスコープがないか、 **または** キーが属していないワークスペースを対象にしています。Roboflow はリソースの存在有無を意図的に隠します。 | `{"error": {"message", "type", "hint"}}` 権限/ワークスペースの場合は `{"error": "string"}` 未知の `keyId`. | | `409` | キーは保護されており、無効化/失効できません。 | `{"error": "string"}` | {% hint style="warning" %} **2 つのエラーボディ形式。** ほとんどのエンドポイントは **string** エラーを返します - `{"error": "Some message"}`。一方、認証/権限レイヤーは **オブジェクト** - `{"error": {"message": "…", "type": "…", "hint": "…"}}` を返します（権限/誤ったワークスペース `404` 上記、およびキーが欠落または無効な場合は `401`）。両方を扱うコンシューマーを作成してください **両方** の形式。 {% endhint %} よくある落とし穴: 単にそのルートのスコープを持たない資格情報によるリクエストは **`404`**ではなく、 `403`。 `403` は、その呼び出しが *は* キーの管理は許可されているのに、呼び出し元が持つ以上の権限を渡そうとしたことを意味します。 参照 [エラーとステータスコード](/reference/ja/errors-and-status-codes.md) 一般的なエラー形式については。 ## CLI この `roboflow api-key` コマンドグループを使うと、ターミナルからワークスペースの API キーを管理できます。これは次をラップします。 [API キーの REST エンドポイント](#http-api) を呼び出し、CLI 設定からワークスペースと資格情報を使用します（参照 [CLI のインストールとセットアップ](/reference/ja/purattofmu/cli/install-and-set-up-the-cli.md)). {% hint style="info" %} 完全なシークレット値は **のみ** キーを作成したときに表示されます。すぐに保存してください。list/get では二度と表示されません。 {% endhint %} ```bash roboflow api-key --help ``` | コマンド | 説明 | | --------- | ------------------------------- | | `list` | ワークスペースの API キーを一覧表示します。 | | `get` | 1つのキーの詳細を表示します。 | | `作成` | 新しいキーを作成します（シークレットは1回だけ表示されます）。 | | `更新` | キーの名前、スコープ、またはメタデータを更新します。 | | `protect` | キーを保護済みとしてマークします。 | | `disable` | キーを無効化または再有効化します。 | | `失効` | キーを完全に取り消します。 | | `公開可能な` | ワークスペースの公開キーを出力します。 | 追加する `--json` （コマンドの前に置くグローバルフラグ）を付けると、スクリプト用の機械可読な出力を取得できます。例: `roboflow --json api-key list`. ### キーを一覧表示する ```bash roboflow api-key list roboflow api-key list --include-disabled --include-folders ``` ### 1つのキーを取得する キーはそれぞれの `keyId` によって指定されます（ `list`): ```bash roboflow api-key get ``` ### キーを作成する ```bash # 呼び出し元の資格情報のスコープを継承します（呼び出し元がフルアクセスの場合はフルアクセスキー） roboflow api-key create "my-app" # スコープ付きキー（--scope を繰り返し指定。Advanced API Keys が必要） roboflow api-key create "inference-only" --scope model:infer # ロールのプリセット - RBAC ロールのスコープを付与します（組み込みまたはカスタムロール名）; # 明示的なスコープと組み合わせ可能。role:owner はフルアクセスを意味します。 roboflow api-key create "reviewer-bot" --scope role:reviewer --scope model:infer # フォルダスコープ付き + 保護済み roboflow api-key create "edge-device" --folder --protected # メタデータを付与する（--metadata を繰り返し指定。Advanced API Keys が必要） roboflow api-key create "ci-key" --metadata team=vision --metadata env=prod ``` シークレットは1回だけ表示されます。スクリプトで取り込むには `--json` を実行して `jq`: ```bash roboflow --json api-key create "ci-key" | jq -r .key > .env.key ``` {% hint style="warning" %} `--scope`, `--folder`順序に一致するように並べられ、 `--metadata` には Advanced API Keys のプラン機能が必要であり、コマンドを実行している資格情報がすでに持っている権限しか付与できません。 {% endhint %} ### キーを更新する ```bash # 名前を変更する roboflow api-key update --name "renamed-key" # キーのスコープを置き換える（--scope を繰り返し指定） roboflow api-key update --scope model:infer --scope project:read # キーのメタデータを置き換える（--metadata を繰り返し指定） roboflow api-key update --metadata team=vision --metadata env=prod ``` `--scope` **置き換えます** キーの既存スコープを、指定したセットと完全に置き換え、 `--metadata` キーのメタデータを置き換えます。 `--name` だけを送れば、どちらにも触れずに名前を変更できます。 {% hint style="warning" %} スコープまたはメタデータの変更には **プラン機能が必要です（それ以外の場合** プラン機能が必要です（ `--name` での名前変更は必要ありません）。 `作成`と同様に、コマンドを実行している資格情報がすでに持っているスコープしか付与できません。 {% endhint %} ### キーを保護 / 保護解除する ```bash roboflow api-key protect ``` 保護されたキーは、CLI、API、または MCP から無効化したり取り消したりできません。 **保護解除は** [**行えます**](https://app.roboflow.com/settings/api) でのみ行えます - 意図的に `unprotect` コマンドは存在しないため、自動化ワークフローが1ステップで安全保護を外して本番キーを取り消すことはできません。 ### キーを無効化 / 再有効化する ```bash roboflow api-key disable # 無効化 roboflow api-key disable --enable # 再有効化 ``` 無効化されたキーは API に拒否されますが、再有効化できます。保護されたキーは無効化できません。 {% hint style="warning" %} `roboflow api-key disable` （および `--enable`での再有効化）は **プラン機能が必要です（それ以外の場合** プラン機能が必要で、スコープ付き `作成` で `--scope`/`--folder`と同じです。これは [REST API](#update-an-api-key). {% endhint %} ### キーを取り消す ```bash roboflow api-key revoke # 確認を求める roboflow api-key revoke --yes # プロンプトを省略する（スクリプト用） ``` 取り消しは永続的です。保護されたキーは CLI から取り消せません - 先にダッシュボードで保護を解除してください。 ### 公開キーを取得する ```bash roboflow api-key publishable roboflow --json api-key publishable | jq -r .publishableKey ``` 公開キー（`rf_`）はシークレットではなく、ブラウザ / [inferencejs](https://docs.roboflow.com/deployment/self-hosted/sdks/web-browser) コードに埋め込んでも安全です。これは推論専用で、作成も取り消しもできません。参照 [公開可能キー](#the-publishable-key) を使用します。詳しくは