> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 API キー

> Phaseo コントロールプレーン API 用に、権限を絞った管理キーを作成します。

管理 API キーは、クレジット、アクティビティ、ワークスペース管理、キー管理、プリセット、設定、ガードレールなど、Phaseo のコントロールプレーンで使うサーバー側の認証情報です。推論リクエストの送信には使用しません。

**ダッシュボード → 設定 → 管理キー** で作成します。シークレットが表示されるのは一度だけです。ダイアログを閉じる前に、シークレットマネージャーへ保存してください。

## 認証情報の種類

| 認証情報 | 用途 | 制御する内容 |
| - | - | - |
| Gateway API キー | モデルおよび生成リクエスト | ルーティングポリシー、予算、制限、適用済みガードレール |
| 管理 API キー | コントロールプレーンへのリクエスト | 明示的な管理機能とワークスペースのロールチェック |
| OAuth アクセストークン | 委任されたコントロールプレーンへのアクセス | 承認済み OAuth スコープとワークスペースのロールチェック |

管理ルートで受け付けるのは `phaseo_v1_mk_<kid>_<secret>` のみです。Gateway API キーは `phaseo_v1_sk_<kid>_<secret>` を使用し、推論専用です。コントロールプレーンのエンドポイントにはアクセスできません。

管理キーはサーバー側のコードからのみ使用してください。

```http theme={null}
Authorization: Bearer phaseo_v1_mk_<kid>_<secret>
```

本番環境のベース URL:

```text theme={null}
https://api.phaseo.app/v1
```

## アクセスレベルを選択する

ダッシュボードでは明示的なテンプレートを選べます。キーの作成時に、各テンプレートは一覧に記載された機能へ展開されます。Phaseo は `all` のようなワイルドカードを保存しません。そのため、新しい権限が追加されてもキーに暗黙で付与されることはありません。

| テンプレート | 付与される権限 |
| - | - |
| **Read** | 現在の管理用 `*:read` 機能すべて |
| **Write** | 現在の `*:read` および `*:write` 機能すべて。削除権限はありません |
| **All** | 現在の読み取り、書き込み、削除の管理機能すべて |

## 機能リファレンス

一般的な用途にはアクセステンプレートを使用します。連携に目的を絞った小さな権限セットが必要な場合は、機能を個別に指定してください。

| 領域 | 読み取り | 書き込み | 削除 |
| - | - | - | - |
| ID とカタログ | `me:read`、`models:read`、`providers:read`、`pricing:read` | — | — |
| 使用状況と可観測性 | `credits:read`、`activity:read`、`analytics:read`、`generations:read`、`feedback:read` | `feedback:write` | — |
| ワークスペース | `workspaces:read` | `workspaces:write` | `workspaces:delete` |
| Gateway API キー | `keys:read` | `keys:write` | `keys:delete` |
| 管理 API キー | `management_keys:read` | `management_keys:write` | `management_keys:delete` |
| プリセット | `presets:read` | `presets:write` | `presets:delete` |
| 設定 | `settings:read` | `settings:write` | — |
| プロバイダーの認証情報 | `provider_credentials:read` | `provider_credentials:write` | `provider_credentials:delete` |
| プライベートモデル | `private_models:read` | `private_models:write` | `private_models:delete` |
| ガードレール | `guardrails:read` | `guardrails:write` | `guardrails:delete` |
| 予算 | `budgets:read` | `budgets:write` | `budgets:delete` |
| OAuth クライアント | `oauth_clients:read` | `oauth_clients:write` | `oauth_clients:delete` |

`Write` テンプレートには対応する読み取り権限も含まれるため、連携側でリソースを確認してから更新できます。`All` には削除権限も含まれます。信頼できる管理用自動化にのみ使用してください。

## スコープとワークスペースのロール

スコープは必要ですが、それだけでは十分ではありません。Phaseo はキーまたは OAuth プリンシパルが対象のワークスペースに属し、必要なワークスペースロールを持つことも確認します。スコープ付きキーでも、別のワークスペースへのアクセスや所有者・管理者チェックの回避はできません。

たとえば `keys:write` はキー管理操作を許可します。呼び出し元がそのワークスペースのキーを管理できるかどうかは、ワークスペースのロールチェックで判定します。

## ガードレールは別の仕組みです

ガードレールは **Gateway API キー** に適用され、推論トラフィックを制御します。対象は、ルーティング制限、予算、プロンプトインジェクションへの対処、機密情報に関するルールです。管理キーのスコープは、認証情報が呼び出せる管理 API を決めます。これらは相互に補完する制御であり、代替にはなりません。

推論キーにガードレールを適用する方法は、[API キーにガードレールを導入する](../cookbook/guardrails-for-api-keys.mdx)を参照してください。

## セキュリティとローテーション

* 管理キーをブラウザー、デスクトップログ、ソース管理、チャットに含めないでください。
* 連携ごとに専用キーを用意し、権限が最も狭いテンプレートを選んでください。
* 連携に無期限のアクセスが必要ない場合は、有効期限を設定してください。
* 使用しなくなったキーはすぐに停止または削除してください。
* キーが漏えいした場合は、調査を続ける前にローテーションしてください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.