---
title: 管理者APIキー
description: AI agentsやスクリプト用ak_管理者キーの作成と失効：8つのスコープ、有効期限、IP範囲、レート制限、実行できない操作、全エラーコードを解説します。
url: https://nexcmp.com/ja/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 管理者APIキー {#admin-api-keys}

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

## 動作内容 {#what-it-does}

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

::: info カスタマーキーとは異なります
お客様はカスタマーポータルで`vk_`で始まるキーを作成します（[APIキーとスコープ](https://nexcmp.com/ja/docs/developers/api-keys/)）。これらはカスタマーAPIおよび`/mcp`にのみアクセスできます。`ak_`キーはカスタマーAPIで拒否され、`vk_`キーはadmin APIで拒否されます。
:::

## 要件 {#requirements}

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

## キーの作成 {#create-a-key}

1. **System › Settings › API & AI agents** を開き、**API keys**タブを表示したままにします。
2. **Create new key**をクリックします。
3. フォームに以下を入力します：

   | 項目 | ルール |
   |---|---|
   | Name | 60文字まで。「Claude Code on my laptop」など。 |
   | Scopes | 少なくとも1つチェックを入れてください。[Scopes](#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**タブを開くと、作成したばかりのキーがすでに入っている貼り付け用のコマンドを取得できます（このページのみ、再読み込みするまで）。

![名前、スコープのチェックボックス、有効期限、IP範囲が入力された新しいキーのダイアログ](https://nexcmp.com/ja/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![コピーボタンと警告が表示され、新しいキーが一度だけ表示されるダイアログ](https://nexcmp.com/ja/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Scopes {#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キーの書き込み。これらは設定可能ですが、読み出すことはできません。 |

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

## キーの失効 {#revoke-a-key}

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

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

## キーで絶対に実行できない操作 {#what-a-key-can-never-do}

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

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

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

### 確認が必要な操作 {#actions-that-need-your-confirmation}

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

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

## 2段階確認 {#two-step-confirmation}

呼び出しに確認が必要な場合、何も変更されません。応答は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-limit-and-ip-rules}

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

## アクティビティログ {#activity-log}

**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ごとの呼び出しをリストするActivityタブ](https://nexcmp.com/ja/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## 確認 {#verify}

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

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

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

```bash
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](https://nexcmp.com/ja/docs/configure-with-ai/mcp-admin/) で説明されています。

## エラー {#errors}

エラーは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` | ツールの引数が不足している、不明である、または型が間違っています。メッセージにその名前が示されます。 | 引数を修正してください。 |

## 制限と注意事項 {#limits-notes}

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