---
title: APIキーとスコープ
description: お客様がAPIキー（vk_ prefix）を作成し、スコープを選択し、IPや有効期限で制限する方法と、管理者がそれを確認・無効化する方法を説明します。
url: https://nexcmp.com/ja/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# APIキーとスコープ {#api-keys-and-scopes}

> **ポータルでの場所:** API keys (`/api-keys`)。 **管理画面での場所:** Customers › Customers › API keys (`/customers/apikeys`)。

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

**API key**を使用すると、スクリプト、CIジョブ、[`cmp` CLI](https://nexcmp.com/ja/docs/developers/cmp-cli/)、またはAIアシスタント（[MCP](https://nexcmp.com/ja/docs/developers/mcp/)）が、付与された権限（**スコープ**）の範囲内で、1人の顧客に代わって[REST API](https://nexcmp.com/ja/docs/developers/api/)を呼び出すことができます。顧客キーは`vk_`で始まります。サービスの閲覧や管理を行うことができますが、金額やアカウント自体に触れることは**絶対にできません**。

## 要件 {#requirements}

| 項目 | 要件 |
|---|---|
| 顧客 | サインイン済みのポータルセッション（キーで他のキーを作成・編集することはできず、顧客になりすました管理者でも同様です）。 |
| スイッチ | APIキーはデフォルトで有効です。無効化されている場合、呼び出しは 401 `api_keys_disabled` を返します。 |
| 依存関係 | 製品のスコープは、その製品がサイトで有効になっている場合にのみ表示されます。 |

## キーの作成（顧客） {#create-a-key-customer}

1. ポータルにサインインし、**API keys**を開きます。
2. **Create key**をクリックします。
3. フォームに以下を入力します：

   | 項目 | ルール |
   |---|---|
   | **Key name** | 必須、60文字まで（「deploy server」、「backup script」など）。 |
   | **このキーが実行できる操作** | 必要なスコープにチェックを入れます（少なくとも1つ）。読み取り専用のキーには書き込みスコープを付与しないでください。金銭が発生するスコープやデータを削除するスコープの扱いには十分注意してください。 |
   | **Expiry** | 無期限、30日、90日、または1年（APIでは1〜3650日まで指定可能）。 |
   | **特定のIPからの呼び出しのみを許可** | 1行につき1つのIPまたはCIDRレンジ、最大20個まで（IPv4またはIPv6）。空欄の場合は任意のIPを許可します。可能な限りサーバーのIPを固定してください。 |

4. フォームを確認します。キーは「Key created — shown ONCE」というウィンドウに**一度だけ**表示されます。コピーして **I saved the key** をクリックしてください。保存されるのはSHA-256ハッシュのみであるため、管理者であっても再確認することはできません。紛失した場合は無効化し、新しいキーを作成してください。
5. ポータルには、キーをテストするためのすぐに使える `curl` コマンドも表示されます。


キーは `vk_` とそれに続く長いランダムな文字列で構成されます。リストには最初の文字（例: `vk_a1b2c3d4`）、スコープ、有効期限、最終使用日時、リクエスト数、ステータス（*Active*、*Expired*、*Revoked*）のみが表示されます。

### 編集、無効化、監査 {#edit-revoke-audit}

- **Edit** では名前、スコープ、許可するIP、有効期限を変更できます。なりすましセッション中は許可されません。
- **Revoke** はキーを即座に停止し、元に戻すことはできません。利用ログを参照できるように行は保持されます。
- **Key usage log** には、過去60日間の書き込みコマンドとすべてのエラー（時刻、リクエスト、キー、結果、送信元IP）が表示されます。
- 1つのアカウントでデフォルト最大 **10個のアクティブなキー** を保持できます。
- CLIまたはMCPログインを通じて作成されたキーは **Connected apps & devices** に表示され、そこから取り消すことができます。

## Scopes {#scopes}

スコープ名の形式は `area:action` です。提供されるスコープは有効にしている製品によって異なります。

| Scope | Allows |
|---|---|
| `catalog:read` | プランおよびカタログの読み取り。 |
| `vm:read` | VM、メトリック、VM請求書の読み取り。 |
| `vm:write` | 電源操作、軽微な変更、ファイアウォール、クイックスナップショット。 |
| `vm:create` | **VMの作成（有料）。** |
| `vm:plan` | **プラン変更またはリサイズ（有料）。** |
| `vm:destroy` | **VMの削除。** |
| `vm:restore` | **スナップショットからのVM復元（ディスクが上書きされます）。** |
| `vm:console` | VNCコンソールチケットを開く。 |
| `sshkey:read`, `sshkey:write` | SSHキーの読み取り、追加、削除。 |
| `volume:read`, `volume:write`, `volume:create`, `volume:destroy` | データボリューム（作成と拡張は有料、破棄はデータ消失）。 |
| `backup:read`, `backup:write`, `backup:restore` | Backups（復元によりディスクは上書きされます）。 |
| `billing:read` | ウォレット、請求書、支払い履歴 — **読み取り専用**。 |
| `bandwidth:buy` | **帯域幅アドオンの購入（有料）。** |
| `account:read`, `account:write` | プロフィール、概要、アクティビティ、通知。`account:write` は通知を既読にする操作のみを行います。 |
| `apikey:read` | アカウントのキー一覧および利用ログの表示（作成、編集、取り消しは不可）。 |
| `apikey:self` | すべてのキーに暗黙的に適用: 呼び出し元のキーの検査（`GET /v1/apikeys/self`）。 |
| `ticket:read`, `ticket:write` | サポートチケット。 |
| `aff:read`, `transfer:read` | アフィリエイトプログラムおよびサービス転送 — 読み取り専用。 |
| `k8s:read`, `k8s:write`, `k8s:create`, `k8s:scale`, `k8s:destroy`, `k8s:kubeconfig` | Kubernetes（作成とスケールは有料、kubeconfigはクラスター管理者権限）。 |
| `vpc:read`, `vpc:write`, `vpc:create`, `vpc:destroy` | プライベートクラウド。 |
| `image:read`, `image:write` | OSおよびISOイメージ（ストレージは時間単位で課金されます）。 |
| `s3:read`, `s3:write`, `s3:create`, `s3:destroy`, `s3:keys` | Object Storage（S3シークレットは1回のみ表示されます）。 |
| `vpn:read`, `vpn:detail`, `vpn:write`, `vpn:create`, `vpn:destroy` | VPNおよびIPv6プロキシ（接続詳細にプロキシパスワードが含まれます）。 |
| `dedicated:read`, `dedicated:write`, `dedicated:console`, `dedicated:create`, `dedicated:destroy` | 専有サーバー（ウォレットから注文を作成、破棄するとOSが再インストールされます）。 |
| `shield:read`, `shield:write`, `shield:agent` | DDoSシールド（該当モジュールが有効な場合のみ）。 |

キーのスコープ外の呼び出しには **403 `scope_required`**、どのキーも呼び出せないパスには **403 `endpoint_not_public`** が返されます。

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

どのスコープでも、入金・出金、カードや自動入金の変更、パスワード・メール・2FAの変更、アカウントの削除、他のキーの作成・編集・取り消しを行うことはできません。これらには常にサインイン済みのブラウザが必要です。キーが流出した場合でも、顧客の資金やアカウントにアクセスすることはできません。

## 信頼できるルール {#rules-you-can-rely-on}

| ルール | Detail |
|---|---|
| Site-bound | キーは作成されたサイト（ドメイン）でのみ機能します。 |
| レート制限 | キーごとおよびアカウントごと: デフォルトで毎分120および300リクエスト。 |
| べき等性 | 費用が発生する操作や繰り返せない操作には `Idempotency-Key` ヘッダーが必要です。 |
| クォータ | キーには、顧客と同じ [quotas](https://nexcmp.com/ja/docs/billing/quotas/) が適用されます。 |
| Locked account | ロックされた顧客のキーは動作しなくなります (403 `account_blocked`)。 |
| 監査 | 管理者による無効化は、管理者監査ログに記録されます。 |

## 管理者ビュー {#administrator-view}

1. **Customers › API keys** (`/customers/apikeys`) を開きます。表には、キー名と先頭文字、所有者、スコープ、ステータス、最後の使用状況 (時刻、リクエスト数、IP)、有効期限が表示されます。
2. リセラーがいる場合は、サイトでフィルタリングします。名前、ID、またはキーの先頭で検索します。
3. アクティブなキーを停止するには **Revoke** をクリックし、使用状況を確認するには **Log** をクリックします。
4. 管理者はキーの**閲覧と無効化**を行えますが、顧客のキーの読み取りや作成はできません。

![スコープ、ステータス、最後の使用状況、Revokeボタンが表示された、顧客APIキーの管理者リスト](https://nexcmp.com/ja/docs/images/developers/api-keys-02-admin.webp)

## 確認 {#verify}

1. `vm:read` スコープのみを持つキーを作成します。
2. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` はVMリストを返します。
3. `curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"` は 403 `scope_required` を返します。
4. キーを無効化すると、最初の呼び出しは 401 `key_revoked` を返すようになります。

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

- キーは二度と表示されません。パスワードと同様に扱い、シークレットマネージャーやCIシークレットに保存してください。
- スクリプトごとに1つのキー、最小限のスコープ、短い有効期限、IP許可リストを使用することをお勧めします。古いキーを無効化して新しいキーを作成することでローテーションします。
- デバイスログイン (CLI、MCP) からのキーの有効期限はデフォルトで90日です。
- 削除または転送されたリソースは、キーの無効化の影響を受けません。

## トラブルシューティング {#troubleshooting}

| 症状 | 原因 | 対処法 |
|---|---|---|
| エラー `too_many_keys` (422) | アクティブなキーの制限 (デフォルトで10個) に達した | 古いキーを無効化します。 |
| エラー `invalid_argument`: スコープが選択されていません | スコープにチェックが入っていない | 少なくとも1つのスコープにチェックを入れてください。 |
| 許可されたIPに関するエラー `invalid_argument` | エントリがIPまたは範囲ではない、プレフィックス長が間違っている、またはエントリが20個を超えている | 1行につき1つのIPまたはCIDR (例: `203.0.113.0/24`)。 |
| なりすまし中の作成は拒否されます | `impersonate_forbidden` | 顧客にキーの作成を依頼してください。 |
| 401 `key_expired` | 有効期限が過ぎている | 新しいキーを作成します。 |
| 401 `key_ip_denied` | 呼び出し元IPが許可リストに含まれていない | IPを追加するか、リストをクリアします。 |
| 401 `api_keys_disabled` | 機能が無効になっている | 管理者にお問い合わせください (`api_keys_enabled` 設定)。 |