API リファレンス
現在のTungstoAPIに認証する
アカウント、請求、サーバーエンドポイントと統合する前に、サポートされているセッションCookieとCSRFの契約を理解してください。
始める前に
- 既存のアカウントと、稼働中のアカウントサービスへのHTTPSアクセス。
- リクエスト間でセッションCookieを保持するクライアント。
- 変更の場合、同じアクティブセッションに関連付けられたCSRFトークン。
サポートされている認証方法を使用する
保護されたAPIルートは、サインインによって確立されたアカウントセッションを使用します。セッションCookieの名前は__Host-tungsto-sessionで、SecureおよびHttpOnlyとしてマークされています。2番目のCookieである__Host-tungsto-csrfは、リクエスト検証をサポートします。アカウント変更には、セッションCookieに加えて、そのセッションと一致するx-csrf-tokenヘッダーが必要です。
SSH & APIキー画面では、スコープ付きキーの作成、一覧表示、失効ができます。Authorization: Bearerの後にワンタイムキーを続けて送信してください。読み取りスコープはGET /api/v1/servers、サーバー詳細、/api/v1/ordersを許可します。サーバースコープはサーバー、サーバー詳細、/api/v1/networkを許可します。請求スコープはGET /api/v1/ledger.を許可します。ブラウザセッションが存在していても、すべてのAPIキー変更は拒否されます。パスワード変更またはアカウント回復により既存のキーは失効します。このローカルプレビューを基に無人本番ハードウェアや支払い自動化を構築しないでください。
セッションを確立して検証する
上記のリクエストはフィールド名のみを示しています。資格情報は自分のクライアントで安全に提供し、共有例や診断出力に実際のパスワードを保存しないでください。ブラウザからのリクエストは同じサイトに留まる必要があります。別のオリジンを指定するOriginヘッダーは拒否されます。
- ユーザー名とパスワードを含むJSON POSTを/api/v1/auth/loginに送信します。成功したレスポンスで返されたSet-Cookie値をクライアントの保護されたCookieストアに保持します。
- JSONレスポンスで返されたcsrfTokenをそのセッションで保持してください。あるサインインからのトークンを別のサインインのクッキーと混在させないでください。
- アカウントを確認するには、Cookieを指定してGET /api/v1/meを呼び出します。その応答には、username、balanceUsd、csrfTokenが含まれます。
- 保護された変更の場合、セッションCookie、Content-Type: application/json、x-csrf-tokenを送信してください。エンドポイントが必要とする場合はIdempotency-Keyを含めてください。
- クライアントが終了したら、POST /api/v1/auth/logoutを使用してセッションを終了してください。
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}セッションの有効期限と検証エラーを処理する
アカウント回復が成功すると、パスワードが変更され、既存のセッションが失効し、交換用の回復コードが発行されます。以前のCookieを使用しているクライアントは再度認証する必要があります。サービスはセッションも期限切れにするため、以前に成功した接続が無制限の資格情報になることはありません。
| 応答 | 意味 | 次のアクション |
|---|---|---|
| 401 authentication_required | 有効なアカウントセッションが見つかりませんでした。 | 再度サインインし、新しい Cookie を保持します。 |
| 401 session_invalid | セッションとCSRF Cookieは一緒に検証されません。 | 混在したクッキーを再利用する代わりに、新しいサインインを開始してください。 |
| 403 csrf_failed | 変更リクエストに対応する検証トークンがありません。 | セッション情報を再読み込みし、現在のトークンを使用してください。 |
| 403 origin_rejected | 提供されたOriginがリクエストのOriginと異なります。 | サポートされている同一サイトのコンテキストからリクエストを実行します。 |
| 429 rate_limited | 認証試行回数が多すぎます。 | 再試行する前に待機してください。継続的に再試行しないでください。 |
統合を現在の契約内に保つ
セキュリティ画面にはGET /api/v1/sessionsを介したアクティブなセッションが一覧表示され、DELETE /api/v1/sessions/:id.を介して所有するセッションを取り消します。キー画面にはAPIキーが一覧表示され、取り消すことができます。OAuthフローはありません。登録と回復は対話型のアカウントアクセス操作であり、サービスアカウントメカニズムの代替ではありません。1人のセッションCookieを複数のツールやユーザー間で配布しないでください。
認証成功の受信はアカウントアクセスを確認しますが、すべての外部操作が利用可能であることを確認するものではありません。暗号通貨決済には接続されたプロバイダーが必要です。物理サーバーアクションにはオペレーターがキューに入れられたリクエストを実行する必要があります。成功した応答を完了した実世界のアクションと解釈する前に、エンドポイント固有の結果と再試行動作について運用ガイドを読んでください。