> 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/scoped-api-keys.md).

# 高度な API キー

Advanced API Keysでは、スコープ付き権限、フォルダーキー、カスタムメタデータ、無効化、デフォルトキー、ローテーションのリマインダーがワークスペースAPIキーに追加されます。

{% hint style="info" %}
Advanced API Keys は Enterprise アドオンです。 [営業担当に問い合わせる](https://roboflow.com/sales) か、アカウント担当者に連絡して、ワークスペースで有効にしてください。
{% endhint %}

すべてのワークスペースで、API キーの作成、名前の設定、ローテーション、保護、取り消しができます（ [ダッシュボードで API キーを管理する](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys-in-the-dashboard.md)を参照）。Advanced API Keys を使うと、以下の管理機能が追加されます。有効にしていない場合、ダイアログではこれらの項目がロックされて表示されます。

## スコープ付きキー

スコープ付きキーが持つ権限は、キーに選択したものに限られます。エッジデバイスで推論を実行するキーに、プロジェクトの削除や他のキーの読み取り権限は必要ありません。

キーの作成時、「Generate New API Key」ダイアログの「Key Permissions」には、セクションごと（例: 「Workspace」、「Projects」、「Workflows」、「Images」、「Models and inference」、「API keys」）にすべての権限が表示されます。「API keys」以外はすべて選択されているため、オプトインしない限り、新しいキーで他のキーを読み取ったり管理したりすることはできません。キーに不要な項目のチェックを外すか、「Deselect all」を選択して、必要な項目だけを選んでください。

後からキーの権限を変更するには、キーの行にある「Scoped」または「Full access」バッジ、あるいは「Edit」アイコンをクリックします。保護されたキーの権限を変更するには、保護を解除する必要があります。

キーにない権限を必要とするリクエストは、ルートが存在しない場合と同様に 404 を返します。「 [エラー](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys.md#errors).

API と CLI からは、次の値を使ってキーのスコープをロールの権限に設定することもできます。 `role:<name>` （例: `role:reviewer`）。「 [API キーを作成する](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys.md#create-an-api-key).

<figure><img src="https://1568109427-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmbAGf4KNeNPXGuUuKYv%2Fuploads%2Fgit-blob-657bc4af588af71a418cd3e13ec76dc76f540b9f%2Fapi-keys-generate-dialog-advanced.png?alt=media" alt="Generate New API Key dialog with metadata, default key, rotation due date, owners and key permissions"><figcaption><p>を参照）。Advanced API Keys を使った「Generate New API Key」: セクションごとに「Custom Metadata」、デフォルトキーのチェックボックス、「Rotation Due Date」、「Owners」、「Key Permissions」が表示されています。</p></figcaption></figure>

## フォルダー API キー

フォルダーキーでアクセスできるのは、1 つの [プロジェクトフォルダー](https://docs.roboflow.com/datasets/manage/project-folders)内のプロジェクトと Workflows のみです。サイト、製造ライン、インテグレーションごとにキーを使い分けると、ローテーションや漏えいの影響を 1 つのフォルダーに限定できます。

フォルダーカードのメニューから「API Keys」、「Generate New Key」の順に選択すると、フォルダーキーを作成できます。管理者は、設定の「API Keys」にある「Folder API Keys」セクションでフォルダーを選択して作成することもできます。どちらの場所にも、ワークスペースキーと同じテーブルと行アクションが表示されます。

フォルダーへの書き込みアクセス権を持つメンバーは、フォルダーカードのメニューからそのフォルダーのキーを開けます。キーの管理には、通常のキー権限も追加で必要です。そのため、フォルダーキーはサイトを運用するチームが管理し、ワークスペースキーは管理者が管理する形を保てます。 [推奨アクセス設定](https://docs.roboflow.com/platform/enterprise-features/recommended-enterprise-access-setup#api-keys-in-this-model) では、この方法で構成したロール設定を紹介しています。

フォルダーキーをワークスペースのデフォルトキーにすることはできません。フォルダーキーを使った利用量は、そのフォルダーに計上されます。「 [フォルダー別の請求](https://docs.roboflow.com/platform/billing-and-plans/billing-folders).

<figure><img src="https://1568109427-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmbAGf4KNeNPXGuUuKYv%2Fuploads%2Fgit-blob-05f30f98398bccc8f66b44a80f1dc483b8894e77%2Faccess-setup-folder-menu.png?alt=media" alt="Folder card menu with the API Keys entry"><figcaption><p>を参照）。フォルダーカードのメニューには、「Folder Usage」と「Set Permissions」の隣に「API Keys」があります。</p></figcaption></figure>

<figure><img src="https://1568109427-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgmbAGf4KNeNPXGuUuKYv%2Fuploads%2Fgit-blob-db4670d46179500929c5fdba70d6389d4e9c4578%2Faccess-setup-folder-api-keys.png?alt=media" alt="API Keys dialog for one folder with three keys"><figcaption><p>1 つのフォルダーの「API Keys」: 利用者名を付けたキー、うち 2 つにはメタデータで所有者を設定し、すべてにローテーション日を設定しています。「Generate New Key」も表示されています。</p></figcaption></figure>

## カスタムメタデータ

キーには、キーと値のペアを最大 20 個追加できます（例: `owner=platform-team`, `env=prod`, `cost-center=4711`）。キーの長さは最大 100 文字、値の長さは最大 500 文字です。「Generate New API Key」または「Edit」の「Custom Metadata」の下にある「Add Field」をクリックします。いずれかのキーにメタデータが設定されると、テーブルに「Metadata」列が表示されます。

メタデータを使って、キーの担当者と用途を記録できます。ローテーションのリマインダーが届いたとき、メタデータを見れば誰に問い合わせればよいかわかります。

## 無効化と有効化

一時停止アイコンを使うと、キーを取り消さずに無効化できます。再び有効にするまで、利用者には認証エラーが返されますが、キーの値は変わりません。キーを取り消す前に、そのキーに依存するものが残っていないことを確認するために使います。保護されたキーは無効化できません。

## デフォルトキー

複数のキーがある場合、コードスニペットやバックグラウンド処理でアプリに使用させるキーで、「Set as default API key for this workspace」にチェックを入れます。「 [デフォルトキーと使用中のキー](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys-in-the-dashboard.md#default-and-in-use-keys).

## ローテーション期限と所有者

キーに「Rotation Due Date」と「Owners」を設定すると、キーが有効な間、期限の 15 日前から期限当日までの間にメールが 1 通届きます。キーのテーブルには各期限までの日数が表示され、キーをローテーションすると期限が先に延びます。「 [ローテーションリマインダー](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/rotate-api-keys.md#rotation-reminders).

## API、CLI、MCP サーバーから

デフォルトキーを除き、上記のすべての機能をプログラムから利用できます。作成時には次の項目を指定できます。 `scopes`, `folderIds`, `customMetadata`, `rotationDueAt` および `owners`。更新時に指定できるのは `scopes`, `customMetadata`, `disabled`, `rotationDueAt` および `owners`です。キーに割り当てるフォルダーは作成時に固定されます。デフォルトキーはダッシュボードでのみ選択できます。詳しくは、 [API Key Management API](https://docs.roboflow.com/reference/ja/ren-zheng/authentication/manage-api-keys.md).

## Cloud Streaming

Cloud Streaming は、ワークスペースに紐づく認証情報を `https://api.roboflow.com`で使用します。リクエストパス内のワークスペースは、認証情報のワークスペースと一致している必要があります。URLでのキーの意図しない露出を減らすため、 `Authorization: Bearer` ヘッダーを `api_key` クエリパラメーターよりも優先して使用してください。

連携には、タスクに必要なスコープのみを付与してください。

<table data-search="false"><thead><tr><th>タスク</th><th>必要なスコープ</th><th>認証情報</th></tr></thead><tbody><tr><td>ソースとジョブの一覧表示、ジョブまたはWorkflowインターフェースの読み取り、完了したファイル結果のダウンロード</td><td>video-inference-job:read</td><td>ワークスペースAPIキーまたはOAuthアクセストークン</td></tr><tr><td>一時セッションの割り当てまたは停止、ソースプレビューのリクエスト、ジョブのキャンセル、プレビュー所有者リースの更新、出力の監視</td><td>video-inference-job:create</td><td>ワークスペースAPIキーまたはOAuthアクセストークン</td></tr><tr><td>Workflowジョブの開始</td><td>video-inference-job:create、workflow:read、model:infer</td><td>ワークスペースAPIキー</td></tr></tbody></table>

ソースを検出して処理を開始し、進行状況を読み取り、ジョブを停止する一連の連携には、2つの動画ジョブスコープに加えて、 `workflow:read` および `model:infer`が必要です。ジョブの実行には、リクエストを許可したものと同じAPIキーが使用されます。OAuthアクセストークンではジョブの読み取りと制御はできますが、開始はできません。

デバイスに紐づくキーは、ワークスペース全体を対象とするCloud Streaming制御APIを使用できません。フォルダーにスコープを限定した認証情報では、ジョブの作成や変更、プレビュー／監視用の許可のリクエスト、一時セッションの割り当てや停止はできません。これらの操作にもプロジェクトフォルダーの制限が適用されると想定せず、専用ワークスペースでワークスペーススコープの自動化キーを使用してください。

監視リクエストは読み取りではなく変更操作です。動画の公開をアクティブな状態に保ち、すべての視聴者に対して選択される画像出力を変更する可能性があります。ソースプレビューも需要と配置に影響します。そのため、どちらにも `video-inference-job:create`.

APIキーはサーバー側で管理してください。ソースプレビュー、一時的な公開、ジョブ監視のレスポンスには、機密性の高い接続URLやトークンが含まれます。ログ、分析データ、チケット、共有ドキュメントには保存しないでください。ジョブレコードには、実行認証情報とWorkflowパラメーター値は含まれません。実行内容が変わった場合は、古い認証情報を再利用せず、監視許可を再取得してください。

詳しくは、 [Cloud Streaming](https://docs.roboflow.com/deployment/roboflow-cloud/cloud-streaming) でソースとジョブのライフサイクルをご確認ください。各操作のフィールドについては、 [Platform APIリファレンス](https://docs.roboflow.com/reference/ja/platform/rest-api/platform-api-openapi.md#cloud-streaming) をご覧ください。アプリのソース管理、再起動、昇格、ブラウザーキャプチャにはAPIエンドポイントがありません。これらの操作にはWebアプリを使用してください。
