より落ち着いたコントロールプレーン。

明確なリソースモデル

連携は、明示的なサーバー識別子、リージョン、イメージ、プラン、操作で動作する必要があります。作成や再インストールのリクエストは、完了まで確認できる操作を返すべきです。HTTPリクエストの成功は、マシンが準備完了であることとは異なります。

限定的な役割を持つ認証情報

APIトークンは個別に失効可能とし、必要最小限のリソースとアクションに制限する必要があります。シークレットマネージャーまたは保護された環境に保管してください。小さなバックエンドの記述を避けるためだけに、トークンをブラウザに送信しないでください。

再試行は安全でなければならない

操作が受け付けられた後にネットワークタイムアウトが発生する場合があります。作成および支払いに関わるリクエストには冪等性キーを使用し、操作状態を確認し、レート制限を遵守してください。再試行は不確実性を解消するものであり、追加の課金対象サーバーを作成するものではありません。

統合前に互換性を確認

統合を構築する前に、リリースされた API のバージョン、認証モデル、エラー形式、ページネーション、レート制限、トークンスコープを確認してください。検証済みのリリースリンクから公開された KoalaVPS SDK パッケージのみを使用してください。

API ロードマップ

APIのロードマップは、カタログの検出、認証、アカウント状態、暗号資産請求、サーバーライフサイクル、公開SSH鍵、Webhookを対象としています。以下のルートはインターフェース契約を記述したものであり、本番環境でのアクセスはまだ利用できません。

認証とアカウントのルート

APIの契約では、ログインセッションとAPIキーが分離されています。レスポンススキーマ、エラー、トークンの有効期間、サポートされる復旧アクションを、統合向けにリリースされたバージョンと照合して確認してください。

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

カタログと請求の経路

カタログの閲覧には支払いは不要です。支払いの作成には制限された請求スコープ、明確な請求書の状態、冪等な処理が必要です。サービス有効化の前に確認を完了する必要があります。

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

サーバーとアクセス経路

ライフサイクルでは、キャンセルおよび再インストール操作に明示的な確認が必要です。プライベートな SSH 鍵はクライアント側に保管し、サービス側には公開鍵のみが必要です。

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

イベントと公開情報

Webhookには検証可能な署名、上限付きの再試行、リプレイ保護が必要です。公開信頼エンドポイントは、合成された保証ではなく、実際の日付付き証拠を返すべきです。

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

認証とトラフィック制限

候補となるスコープモデルはread、servers、billing、fullで、アカウントあたり最大10個の有効キーです。API契約では、APIキーに対して毎分120、毎時3,000、公開トラフィックに対して毎分30のリクエスト予算を提案しています。リリース済みのAPIドキュメントで、HTTP 429、Retry-After、適用期間をご確認ください。これらのロードマップ上の予算は、本番容量の確約ではありません。

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDKとプロトコルのリリース

統合ロードマップにはREST、ホスト型MCPエンドポイント、バージョン管理されたstdioパッケージ、SDK、CLIが含まれます。クライアントをインストールする前に、リリースの提供状況、サポート対象ランタイム、チェックサム、API互換性を確認してください。本番用ダウンロードはまだ利用できません。

責任別にグループ化されたAPIリソース

意図された API は、アカウントアクセス、カタログの読み取り、請求、サーバーライフサイクル、SSH キー、コールバックを分離します。読み取り専用の呼び出しは注文を作成すべきではなく、請求用の認証情報がアカウントセキュリティの変更を自動的に許可すべきではありません。これは統合契約を説明するものです。本番のプロビジョニングエンドポイントとリリースされた SDK は、このサイトでは利用できません。

• アカウント：セッション、利用状況、セキュリティ監査イベント
• カタログ：プラン、リージョン、利用可能なイメージ
• サーバー：作成、確認、変更、キャンセル
• SSH 鍵：公開情報を登録し、不要になった鍵を取り消す
• Webhook：署名付きコールバックの登録、検査、テスト、削除

サーバーリクエストは小さく保つべきです

標準プランの識別子、リージョン、OSイメージ、ホスト名を選択してください。ホスト名の上限は 64 文字を想定しています。稼働中のサービスでは、管理者シークレットを非公開で生成するか、登録済みの SSH 公開鍵を受け入れることができます。標準プランのリクエストによって、任意のディスク、GPU、NIC、IPの追加が含意されるものではありません。推測によるアップグレードを無言で課金するのではなく、サポートされていないフィールドは拒否してください。

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

スコープとキーの制限は契約の一部です

提案されている権限グループは、読み取り、サーバー、請求、およびアカウント全体の管理です。キーは作成時に一度だけ表示し、非公開で保管し、ユーザーのパスワードとは独立して失効させる必要があります。想定されるアカウント上限は有効キー10個です。実装を公開する前に、各操作が必要なスコープを持たないキーを拒否することを検証してください。

レート制限と再試行の動作を併せて公開する

提案されている制限は、APIキーで毎分120リクエストおよび毎時3,000リクエスト、未認証の公開カタログリクエストで毎分30リクエストです。これらは計画上のポリシー値であり、実測されたAPI容量ではありません。実際の実装には、一貫した429レスポンス、Retry-Afterのガイダンス、および上限付きのクライアントバックオフが必要です。作成および支払いのリクエストには、安定した冪等キーも必要です。

Webhook は複数回受信される可能性があるメッセージです

コールバック受信側は、元のボディに対する署名を検証し、許容時間枠外のタイムスタンプを拒否し、処理済みのイベント識別子を記憶する必要があります。確認応答の前にイベントを永続化し、その後で変更を冪等に適用してください。配信試行と手動リプレイの経路を可視化しておいてください。コールバックは操作に関する観測であり、ペイロードに含まれる無関係な指示を実行する許可ではありません。

ログを秘密の保管庫にせずに監査する

アカウントセキュリティ上必要な範囲で、実行者識別子、操作種別、対象リソース、結果、時刻を記録してください。パスワード、ベアラートークン、秘密鍵、支払いやアプリケーションリクエストの本文全体は、既定では記録しないでください。保持期間、アクセス権、顧客に表示される履歴を明確にしてください。セキュリティ監査証跡と、顧客のアプリケーション内容を検査する権利は別のものです。

成果物は存在する場合にのみ公開する

公開APIの開始には、バージョン管理されたOpenAPIドキュメント、認証手順、エラーの例、および非推奨化プロセスを含めるべきです。将来のCLI、Pythonパッケージ、TypeScriptクライアント、またはMCPサーバーには、実際のリリース、チェックサム、および維持されたドキュメントが必要です。KoalaVPSプロビジョニングパッケージや本番管理エンドポイントは、このサイトを通じてリリースされていません。

もう少し明確に。