APIキーとスコープ

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

動作内容

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

要件

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

キーの作成（顧客）

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

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 が返されます。

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

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

信頼できるルール

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

管理者ビュー

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

確認

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 を返すようになります。

制限と注意事項

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

トラブルシューティング

症状	原因	対処法
エラー 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 設定)。