管理者APIキー

管理画面の場所： System › Settings › API & AI agents (/agent/keys)、API keysタブ。同じページにはConnect an AI、Connected apps、Activityの各タブもあります。

動作内容

管理者APIキー（プレフィックス ak_）を使用すると、AIクライアントまたはスクリプトが、付与された権限に基づいてパネルを管理できるようになります。これは /v1/admin/ および管理者MCPエンドポイント /mcp/admin の管理者APIで機能します。他の場所では機能しません。

カスタマーキーとは異なります

お客様はカスタマーポータルでvk_で始まるキーを作成します（APIキーとスコープ）。これらはカスタマーAPIおよび/mcpにのみアクセスできます。ak_キーはカスタマーAPIで拒否され、vk_キーはadmin APIで拒否されます。

要件

項目	要件
ロール	管理者にサインインしている必要があります。キーで他のキーを作成することはできません。
Demo	デモパネルでは、このページは読み取り専用です：キーの作成も失効もできません。
到達性	クライアントはパネル上の https://cloud.example.com/mcp/admin または /v1/admin/... に到達できる必要があります（IP制限を使用している場合はファイアウォールを確認してください）。

キーの作成

1. System › Settings › API & AI agents を開き、API keysタブを表示したままにします。

2. Create new keyをクリックします。

3. フォームに以下を入力します：

   項目	ルール
   Name	60文字まで。「Claude Code on my laptop」など。
   Scopes	少なくとも1つチェックを入れてください。Scopesを参照してください。最初は admin:read のみにしてください。
   有効期限	1、7、30、60、または90日。デフォルトは30。最大90。有効期限のないキーは作成できません。
   IP範囲（オプション）	1行につき1つのIPv4/IPv6アドレスまたはCIDR（例：203.0.113.0/24、2001:db8::/48）。最大32個。任意のIPを許可する場合は空のままにします。
   1分あたりの呼び出し回数	1〜6000。デフォルトは120。

4. Create keyをクリックします。ダイアログにキーが一度だけ表示されます（例：ak_XXXX）。今すぐコピーしてください：NexCMPはハッシュのみを保存するため、二度と表示することはできません。

5. I have saved the keyをクリックします。Connect an AIタブを開くと、作成したばかりのキーがすでに入っている貼り付け用のコマンドを取得できます（このページのみ、再読み込みするまで）。

Scopes

キーは、そのスコープが許可するツールとエンドポイントのみを使用できます。書き込みスコープには読み取りアクセスが含まれないため、読み取りと書き込みの両方を行う必要があるキーには admin:read も必要です。

Scope	許可される内容
admin:read	設定、カタログ、顧客、請求、ログの読み取り。機密情報は返されません。
catalog:write	プラン、OSテンプレート、クオータ、割引コード。
infra:write	インフラストラクチャソース（CloudStack、Proxmox）、ゾーン、サーバー。
billing:write	決済ゲートウェイ、通貨、請求書、残高。金額に関する操作には確認が必要です。
customers:write	顧客とリセラー。
settings:write	一般設定、ブランディング、メール、法務ページ、モジュール、通知。
ai:write	AIプロバイダーとAI機能。
secrets:write	パスワードとAPIキーの書き込み。これらは設定可能ですが、読み出すことはできません。

シークレットの設定には2つのスコープが必要です

パスワード、APIキー、トークン値（SMTPパスワード、決済キー、Telegramボットトークン、AIプロバイダーキー、CloudStackやProxmoxの資格情報）を含むすべての呼び出しには、secrets:write および そのエリアのスコープ（SMTPの場合は例えばsettings:write）が必要です。シークレットを手動で入力したい場合は、secrets:writeをオフにして管理画面で入力してください。

キーの失効

1. テーブルからキーを見つけます（ステータスがActive、Expired、またはRevoked；Last usedに日時とクライアントが表示されます）。
2. Revokeをクリックして確認します。

キーはすぐに動作を停止します。失効は永続的であるため、再度必要な場合は新しいキーを作成してください。

キーで絶対に実行できない操作

スコープに関わらず、キーがこれらの領域にアクセスすることは一切できません。管理画面へのサインインが必要です。

• 管理者ユーザーの作成・変更、2FAとサインインのセキュリティ、管理者セッション、管理者APIトークンの管理。
• 管理者キー、OAuth接続、AIアカウントの作成・一覧表示・失効、またはAI Consoleの使用。
• パネルのバックアップ・復元、アップデート、またはライセンスの変更。
• 顧客やリセラーとしてのログイン、顧客のコンソールのオープン、VM資格情報やkubeconfigの読み取り、SSHキーの設定、パスワードの送信またはリセット。
• ネットワークおよびルーティングモジュール（BGP、FRR、RTBH、XDP、インターフェイス、静的・ポリシーパブリックルート、NAT）や外部エージェント、ポータル統合の変更。これらは読み取り専用です。
• demo_*、admin_*、ホストリスト、パスキー、再認証、およびCAPTCHAシークレットなどの設定の変更。

ルールでカバーされていないものは、書き込みはデフォルトで拒否され、読み取りにはadmin:readが必要です。

確認が必要な操作

これらはプレビューを承認した後にのみ成功します（Two-step confirmationを参照）：

• 顧客残高やリセラーウォレットの変更、出金、請求レコード、為替レートの変更。
• 価格の変更（プラン価格、一括プラン作成、イメージおよびストレージ価格）や、割引・金額コードの作成。
• 決済ゲートウェイの資格情報またはCloudStack接続の保存。
• 任意の削除、顧客のブロックまたは削除、顧客の制限の変更、リセラーの停止または終了。
• 顧客サーバーに対する操作、または顧客のための有料サーバーの作成。
• サイト全体のスイッチ、サインインセキュリティ設定、一般設定を通じた決済設定の変更。

2段階確認

呼び出しに確認が必要な場合、何も変更されません。応答はHTTP 428 となり、confirm_required、confirm_token、preview（メソッド、パス、理由、新しい値、および利用可能な場合は現在の値）、およびexpires_in: 300が含まれます。

1. クライアントにプレビューが表示されます。
2. 承認後、ヘッダー X-Confirm-Token: <confirm_token> を付加して同じリクエスト（同じメソッド、パス、ボディ）を再送します。MCPツールの場合は、代わりに引数 confirm_token を指定します。
3. トークンは1回のみ有効で、5分後に期限切れになります。

AI Chat用に管理画面内で作成されたキーは、画面上でしか確認できません。応答にはconfirm_in: "ui"が含まれ、管理画面に確認カードが表示されます。AIが承認することはできません。

レートリミットとIPルール

• 分間制限を超えると、呼び出しは rate_limited (HTTP 429) と Retry-After: 60 を返します。
• IPレンジが設定されている場合、他のアドレスからの呼び出しは ip_not_allowed (HTTP 403) を返します。

アクティビティログ

Activity タブには、キーを使用して行われたすべての呼び出しが新しい順にリストされます（時刻、キー、クライアント、リクエスト元の経路（http、mcp、chat、cli、confirm、preview）、メソッドとパス、ツール、HTTPステータス、IP、および（マスクされた）詳細情報）。パス、ツール、またはキー名で検索したり、エラー（HTTP 400以上）または確認待ちの呼び出し（428以上）のみを表示したり、期間を過去1時間、24時間、または7日間に限定したりできます。NexCMPは最新の200,000件のエントリを保持します。キーを介して行われた変更は、Logs › Admin actions にも ak:<admin>/<key name> という名前で表示されます。

確認

IPレンジ内にある任意のマシンから読み取り専用キーをテストします:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

スコープで許可されているツールのJSONリストが取得されます。1つ実行します:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

キーの Last used 時刻が更新され、その呼び出しが Activity に表示されます。ツールの完全なリストとOpenAPI記述（/v1/admin/openapi.json）については、Connect an AI client で説明されています。

エラー

エラーはJSON形式です: {"error": {"code": "...", "message": "..."}}。

HTTP	code	意味	対処法
401	invalid_key	キーが存在しない、形式が不正である、または不明です。admin以外のパスで ak_ キーが使用された場合も返されます。	キーを確認し、/v1/admin/ と /mcp/admin のみで使用してください。
401	key_expired	キーの有効期限が切れています。	新しいキーを作成します。
401	key_revoked	キーは無効化されています。	新しいキーを作成します。
403	ip_not_allowed	呼び出し元のIPがキーのIPレンジ外です。	許可されたIPから呼び出すか、正しいレンジを持つキーを作成してください。
403	local_only_key	AI Chat またはサーバーCLI用に作成されたキーが、別のマシンから使用されました。	これらのキーは、パネルサーバー上でのみ機能します。
403	insufficient_scope	キーにスコープがありません。応答には required_scope が含まれます。	そのスコープを持つキーを作成してください。
403	forbidden_for_keys	エンドポイント、または変更しようとした設定がキーに対して閉じられています。	管理画面で行ってください。
403	demo_read_only	パネルがデモモードであり、呼び出しが書き込みを行っています。	デモではないパネルを使用してください。
403	confirm_in_ui	このアクションは管理画面の画面上で確認する必要があります。	確認カードを承認してください。
428	confirm_required	プレビューの準備ができました。何も変更されていません。confirm_token が含まれます。	プレビューを表示し、X-Confirm-Token を指定して再度実行してください。
409	confirm_expired	トークンが5分以上経過しています。	新しいプレビューのためにリクエストを再度送信してください。
409	confirm_mismatch	トークンが別のリクエストのものです（メソッド、パス、またはボディが異なります）。	同一のリクエストを再度実行してください。
409	confirm_invalid	不明または既に使用されているトークンです。	新しいプレビューのためにリクエストを再度送信してください。
429	rate_limited	この分間の呼び出し回数が多すぎます。	Retry-After までお待ちください。
400	invalid_path	パスに禁止されているシーケンスが含まれています。	通常のパスを使用してください。
413	too_large	ボディが10 MBを超えています。	送信するデータを減らしてください。
400	invalid_argument	ツールの引数が不足している、不明である、または型が間違っています。メッセージにその名前が示されます。	引数を修正してください。

制限と注意事項

• キーの寿命は短くし、権限は最小限に抑えてください。1つのキーを失効させたときの影響を抑えられるよう、クライアントごとに1つのキーを使用することをお勧めします。
• キーの強力さはそのスコープによって決まります。secrets:write と billing:write の組み合わせが最も機密性が高くなりますが、金銭を伴うアクションは引き続きプレビューで停止します。
• （AI Chat やサーバーCLI用に）自動的に作成されたキーの寿命は数分のみであり、パネルサーバーからのみ機能します。
• AIクライアントを即座に遮断するには、キーを失効させます。OAuth接続はConnected appsタブ（OAuth connectors）で失効させられます。