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つが利用できます。

認証が失敗したとき

拒否されたリクエストは標準のエラー本文を返します。detail リスト、AUTH_001のような error_code、短い error_summary です。文言は変わる可能性があるため、HTTP ステータスと error_code で分岐してください。

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

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

トークン形式

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

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

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

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

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

例: トークンの使用方法

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

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