> 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 server](https://docs.roboflow.com/agents/mcp-server)そのため、自動化エージェントは、ダッシュボードから人がコピペしなくても、アプリケーションに必要なキーをプロビジョニングできます。 {% hint style="info" %} **シークレットは一度書き込むと変更できません。** キーの完全な値が返されるのは **のみ** キーを作成（またはロール）したときだけです。その他のすべてのエンドポイントは非機密の `keyId` ハンドルと短い `prefix` 識別用であり、キー本体は返しません。値は安全に保存してください（たとえば `.gitignore`'d `.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）プライベートキー**の場合、さらに [scope](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) が必要で、エンドポイントに一致していなければなりません。 | エンドポイント | 必要な scope | | ---------------------- | ---------------- | | `GET` list / `GET` one | `api-key:read` | | `POST` create | `api-key:create` | | `PATCH` update | `api-key:update` | | `DELETE` revoke | `api-key:revoke` | | `GET` publishable | `workspace:read` | スコープなし（フルアクセス）のプライベートキーは、これらすべてをすでに満たしています。必要な scope が欠けているキーは、そのルートが存在しないものとして扱われます。 [エラー](#errors). {% hint style="warning" %} A [公開可能キー](#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` は、他のエンドポイントでキーを指定するための、安定した非機密ハンドルです。 * `scopes` は `null` スコープなし（フルアクセス）キーでは null であり、スコープ付きキーでは [scope 文字列](/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` scope がないか、属していないワークスペースを対象にしています。権限不足の場合はオブジェクト形式のエラー `{"error": {"message", "type", "hint"}}`；不明な `keyId` 場合は `{"error": "string"}`。詳細は [エラー](#errors). {% endtab %} {% endtabs %} ### APIキーを作成 `POST` `/:workspace/api-keys` 新しいAPIキーを作成します。シークレット値が返されるのは **一度だけ** で `key` フィールドです。 **ヘッダー** | 名前 | 値 | | ------------ | ------------------ | | Content-Type | `application/json` | **本文**
名前型説明必須
namestringキーの人間向けラベル。false
scopesArray<string> | nullキーを次のものに制限します scopes。以下の3つの状態を参照してください。 Advanced API Keys が必要です。false
folderIdsArray<string>キーをこれらのプロジェクトフォルダに制限します。 Advanced API Keys が必要です。false
custom_metadataMap<string, string>最大20個のキー/値ペア（キーは100文字以下、値は500文字以下）。 Advanced API Keys が必要です。false
protectedbooleanキーを protected 状態で作成します。false
{% hint style="info" %} **`scopes` 作成時:** * **省略** — 新しいキーは **呼び出し元の認証情報自身の scopes を継承します** （「自分と同じようなキーを作る」）。これはプランに依存しません。フルアクセスのキーはフルアクセスのキーを作成し、スコープ付きキーは同じ scopes を持つキーを作成します。フォルダも同様に継承されます。 `scopes` ワークスペースに Advanced API Keys 機能があるかどうかにかかわらず、スクリプトの挙動は同じです。 * **`null`** — 明示的な **フルアクセス** （スコープなし）キーです。呼び出し元自身がフルアクセスを持っている必要があります（スコープ付きの呼び出し元は拒否されます。 [サブセットのルール](#privilege-subset-rules)). * **`[]`** （空配列）— 有効なキーですが **権限はありません**；すべてのスコープ付きルートで拒否されます。後で scopes を付与するためのプレースホルダーとして便利です。 * **`["model:infer", …]`** - **スコープ付き** それらの権限ちょうどに対して（ [セクション名](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) たとえば `model` は、そのセクションのすべての scopes を付与します）。 * **`["role:reviewer", …]`** — a [**ロールのプリセット**](/reference/ja/ren-zheng/authentication/scoped-api-keys.md)：作成時にそのロールの scopes に展開されます。組み込みロール（`labeler`, `reviewer`, `owner`）またはカスタムロール名を使用してください； `role:owner` はフルアクセスを意味します。明示的な scopes と組み合わせ可能です。 明示的な `scopes` **array** (`[]`、リスト、または `role:` プリセット）、 `folderIds`、または `custom_metadata` を必要とします。 **Advanced API Keys** のプラン機能です（そうでなければ `403`）。省略すると `scopes` （継承）と `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" %} 呼び出し元はキーを作成できますが、保持している範囲を超える scopes/フォルダの付与を要求したか、ワークスペースのプランに要求された高度な機能が含まれていません。本文: `{"error": "string"}`. {% endtab %} {% tab title="404" %} 認証情報に `api-key:create` scope がないか、属していないワークスペースを対象にしています。本文: `{"error": {"message", "type", "hint"}}`。詳細は [エラー](#errors). {% endtab %} {% endtabs %} {% hint style="danger" %} この `key` フィールドがシークレット値であり、 **のみ** この応答で表示されます。今すぐ保存してください。二度と取得できません。 {% endhint %} ### APIキーを更新 `PATCH` `/:workspace/api-keys/:keyId` キーの名前、scopes、メタデータを更新し、保護を設定するか、有効/無効を切り替えます。 **ヘッダー** | 名前 | 値 | | ------------ | ------------------ | | Content-Type | `application/json` | **本文** （変更したいフィールドだけを送信してください）
名前型説明必須
namestring新しい表示名。false
scopesArray<string> | null新しい scopes （呼び出し元のサブセット）。以下の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つの状態: `scopes`** （PATCH の意味は作成時と少し異なります。フィールドを省略すると変更されません）： * **省略** — キーの既存の scopes は **変更されません**. * **`null`** — キーは **フルアクセス** （スコープなし）になります。これを付与するには、呼び出し元自身がフルアクセスを持っている必要があります。 * **`[]`** （空配列）— キーは有効な認証情報のままですが **権限はありません**. * **`["model:infer", …]`** - **置き換えます** キーの scopes をこの集合ちょうどに（ [セクション名](/reference/ja/ren-zheng/authentication/sign-in-with-roboflow-getting-started.md#available-scopes) はそのセクションのすべての scopes に展開されます）。 送信する `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 ではキーの保護解除はできません）。または、呼び出し元が付与できない scopes を要求した場合。本文: `{"error": "string"}`. {% endtab %} {% tab title="404" %} そのようなキーは `keyId` ワークスペース内で（本文: `{"error": "string"}`), **または** 認証情報に次の `api-key:update` scope がない、または属していないワークスペースを対象にしている場合（本文: `{"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 %} ### キーの保護 A **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_" } ``` 公開可能キーはブラウザ/エッジでの推論に使い、スコープ付きプライベートキーをサーバー側の処理には使ってください。公開可能キーを持つ人は、そのワークスペースのモデルに対して推論を実行し、ダウンロードすることができます。これは「公開可能」な認証情報として意図されたトレードオフです。 ### 権限サブセットのルール 権限の昇格を防ぐため、新しく作成または更新されたキーは、それを作成する認証情報よりも多くの権限を持つことはできません: * これらのエンドポイントを **スコープ付きプライベートキー**で呼び出すと、新しいキーの `scopes` は呼び出し元キーのスコープのサブセットでなければならず、またその `folderIds` フォルダーも呼び出し元キーのフォルダーのサブセットでなければなりません。スコープなし（フルアクセス）のキーは何でも付与できます。 * を使って呼び出すと、 **ユーザーとして動作する 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": "何らかのメッセージ"}`。認証/権限レイヤーは代わりに **オブジェクト** - `{"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 つのキーの詳細を表示します。 | | `create` | 新しいキーを作成します（シークレットは 1 回だけ表示されます）。 | | `update` | キーの名前、スコープ、またはメタデータを更新します。 | | `protect` | キーを保護済みとしてマークします。 | | `disable` | キーを無効化または再有効化します。 | | `revoke` | キーを完全に取り消します。 | | `publishable` | ワークスペースの公開可能キーを表示します。 | 追加 `--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" %} スコープやメタデータの変更には **Advanced API Keys** プラン機能が必要です（ `--name` による名前変更は不要です）。 `create`と同様に、コマンドを実行している資格情報がすでに持っているスコープしか付与できません。 {% 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`による再有効化には **Advanced API Keys** プラン機能が必要です。スコープ付き `create` で `--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) 詳細は ## MCP サーバー AI エージェントを [MCP サーバー](https://docs.roboflow.com/agents/mcp-server) に接続すると、以下のツールで API キーを管理できます：
ツール説明
api_keys_listワークスペースのすべての API キーを一覧表示します。
api_keys_get1 つのキーのメタデータを取得します。
api_keys_get_publishableワークスペースの公開可能キーを取得します。
api_keys_create新しい API キーを作成します。
api_keys_updateキーの名前、スコープ、またはメタデータを更新します。
api_keys_disable取り消さずにキーを無効化または再有効化します。
api_keys_revokeキーを完全に取り消します。