System APIは、APIキー、スマートルーティングキー、およびウォレット操作など、MixRouteアカウント内のリソースを管理します。モデル推論APIとは別のAPIです。
システムアクセストークンは、アカウント単位の管理アクセス権を付与します。ブラウザーのコード、モバイルアプリケーション、ログ、ソース管理には絶対に含めないでください。
システムアクセストークンの取得
MixRouteコンソールでアカウント設定 → APIアクセスを開き、システムアクセストークンを生成してコピーしてください。トークンはシークレットマネージャーに保存してください。
GET /api/user/tokenは、新しいシステムアクセストークンを生成します。これは読み取り操作ではなくローテーション操作であり、以前のトークンを無効にします。通常の自動処理では呼び出さないでください。
認証ヘッダー
認証が必要なすべてのSystem APIリクエストには、両方のヘッダーが必要です。
JSONボディを含むリクエストでは、次のヘッダーも送信してください。
ユーザーIDは、システムアクセストークンに属している必要があります。認証失敗時のHTTPステータスコードは1つに統一されていません。認証情報の欠落やユーザーIDの不一致ではHTTP 401が返される場合があり、無効なアクセストークンでは現在、success: falseを伴うHTTP 200が返されます。HTTPステータスとレスポンスエンベロープの両方を必ず確認してください。
アカウントデータを変更せずに認証を確認するには、このリクエストを使用してください。
レスポンスエンベロープ
大半のシステムAPIエンドポイントは、このエンベロープを使用します。
一部の検証エラーや認証失敗では、success: falseを伴うHTTP 200が返されるため、HTTPのステータスとsuccessフィールドの両方を確認してください。
クォータの単位
アカウントのクォータとAPIキーのクォータは、米ドルそのものではなく、内部クォータ単位で保存されます。現在の換算値は、公開ステータスエンドポイントから取得してください。
以下の式を使用します。
quota_per_unitはデプロイ設定であり、変更される可能性があります。現在の値をハードコードせず、取得して使用してください。
アカウント残高とキーのクォータの違い
- アカウント残高（
GET /api/user/self、フィールドquota）は、そのアカウントで利用できるウォレット残高です。
- キークォータ（
remain_quota）は、1つのAPIキーの利用額の上限です。
- キーにクォータを割り当てても、ウォレットから資金が移動することはありません。
unlimited_quota: trueはキー単位の上限を解除しますが、リクエストは引き続きアカウント残高を消費します。
現在のアカウント残高を取得して表示します。
利用可能なグループ
キーを作成する際は、アカウント固有のグループ一覧を使用してください。
別のアカウントで利用できるグループが、自分のアカウントでも利用できるとは限りません。defaultグループは、このガイドの大半の例に適しています。
セキュリティチェックリスト
- システムアクセストークンはサーバー側で保持してください。
- 自動化には専用のアカウントまたはトークンを使用してください。
- キーの表示用エンドポイントのレスポンスを、決してログに記録しないでください。
- 可能な限り、各APIキーに分かりやすい名前、有効期限、クォータ、IP制限を設定してください。
- キーをローテーションする際は、まず代わりのキーを作成し、トラフィックの移行後に古いキーを無効化して削除してください。
