API認証とBearerトークン

認証の仕組み

1. Quote3Dアカウントに登録してログインしてください。
2. ダッシュボードの「Tokens」タブからAPIトークン（JWT）を生成してください。
3. APIリクエストにトークンを含めます。Authorization: Bearer がサポートされており、X-API-Token も受け入れられます:
   Authorization: Bearer YOUR_TOKEN_HERE
4. サーバーはあなたのトークンを検証し、有効で期限切れでない場合、アクセスを許可します。

トークンスコープ

トークンのスコープは、到達できるエンドポイントを決定します。スコープはトークン作成時に選択し、ダッシュボードのトークンページで確認できます。

• フルアクセス — サーバー側トークンの既定です。プランが許可するすべてのエンドポイントに到達します。
• ウィジェット — ストアに埋め込むトークン用のスコープです。埋め込みウィジェットに必要な範囲に限定され、Webhook、アカウント情報、分析、使用状況、割り当てには到達できません。

トークンのスコープ外のエンドポイントへの呼び出しは、トークン自体が有効でも403で拒否されます。同じトークンが他で動作するのに403で失敗する場合は、まずスコープを確認してください。

トークンのライフサイクル

• トークンの値は作成時に一度だけ表示されます。その後は復元できないため、すぐにシークレットマネージャーへ保存してください。紛失した場合はローテーションして新しい値を取得します。
• トークンには有効期限を設定できます。期限切れのトークンは機能を停止し401を返します。ダッシュボードには各トークンの有効期限が表示されます。
• トークンのローテーションは新しい値を発行し、古い値を直ちに無効化します。古いトークンを使用中のリクエストはすぐ失敗し始めるため、ローテーション前に新しい値をデプロイしてください。
• トークンはIPアドレスのリストに制限できます。それ以外のアドレスからの呼び出しは403で拒否されます — サーバー移設やNATゲートウェイ変更後によくある落とし穴です。
• 保有できるトークン数はプランによって制限されます。無料プランではサーバートークン1つとウィジェットトークン1つが利用できます。

認証が失敗したとき

拒否されたリクエストは、success: falseと短いメッセージを含む標準のエラーエンベロープを返します。文面は変更される可能性があるため、メッセージ本文ではなくHTTPステータスコードで分岐してください。

{
  "success": false,
  "error": "API token has expired"
}

• 401 — トークンが欠落、形式不正、期限切れ、または失効しています。ヘッダー名と、コピー時に値が切れていないかを確認してください。
• 403 — トークンは有効ですが、この呼び出しには許可されていません。よくある原因はスコープ制限か、呼び出し元を含まないIP許可リストです。

トークン形式

Quote3Dのトークンは、ベアラースタイルのAPI認証情報です。クライアントは、トークンを不透明な秘密として扱い、トークンの内部構造に依存しないようにする必要があります。

JWTは3つの部分で構成されます:

1. ヘッダー：署名アルゴリズムとトークンタイプを指定します。
2. ペイロード：ユーザーデータとクレーム（ユーザーID、メールアドレス、有効期限など）が含まれます。
3. 署名：トークンが改ざんされていないことを検証します。

JWTは次のようになります:

連携においては、重要なルールは単純です。トークンを安全に保管し、各リクエストで送信し、連携がクライアントサイドのトークンを明示的に必要としない限り、クライアントコードで解析または公開しないようにしてください。

例：トークンの使用方法

curlを使ってトークンを使用する方法は以下の通りです。認証ヘッダーのスタイルは一貫して使用してください。

または、API Playgroundで、認証モーダル（鍵アイコン）にトークンを貼り付けてセッションを認証してください。カスタム統合では、X-API-Tokenヘッダーをより適切に使用することもできます。