認証モードを選ぶ

SDK を認証する 2 つの方法 — 静的な API キーが必要か、ユーザーごとの session JWT が必要かを判断する決定木。

SDK は 2 つの認証モードをサポートしています。どちらを選ぶかは、SDK を呼び出すコードが実際にどこで動くかによって決まります — どちらが便利かではありません。

決定木

このコードはあなたのサーバー（Node.js backend、cron job、内部サービス）で動いていますか？ → API キーモードが使えます。キーを apiKey として渡します。コンソールのアプリ詳細ページからセルフサービスで発行できます（Regenerate API Key）— API キーを取得するを参照してください。静的なキーを管理したくない場合は、下記の session JWT モードを使ってください。

const ai = new Quravin({
  endpoint: process.env.QURAVIN_URL,
  apiKey:   process.env.QURAVIN_KEY,   // secrets ストアから — 絶対にコミットしないこと
});

このコードはユーザーのブラウザで動いていますか？ → session JWT モードを使ってください。あなたのサーバーがユーザーごとに短期トークンを発行し、ページに渡します — ブラウザは client_secret や静的な API キーを一切見ません。

const ai = new Quravin.Quravin({
  endpoint: "https://api.quravin.com",
  sessionToken: await fetchToken(),   // 自分の backend エンドポイントから
  onTokenExpired: fetchToken,          // 401 時に自動更新
});

`x-api-key` と session JWT —両者は互換ではない

上記の apiKey はリクエストを x-api-key: <key> として送信します。これはレガシーな、アプリ単位の、org に紐づかない資格情報であり、プラットフォームはユーザーごとの JWT へと段階的に移行を進めています。使う前に知っておくべきことが 2 つあります。

org wallet を持たない。 あなたのアカウントが wallet モードの課金であれば、素の x-api-key で認証した課金対象の POST /tickets 呼び出しは、org の wallet に残高があっても 402 insufficient_credits を返します — このキーは org に紐づいていないため、そこから引き落とすことができません。これはバグではなく仕様です。
ユーザーごとの identity を持たない。 すべての呼び出しは特定のユーザーではなく「アプリ」からのものに見えます — cron job には問題ありませんが、ユーザーごとの監査・帰属や、アプリ全体より狭く絞った pipelines[] ACL が必要な場合には向きません。

課金やユーザーごとの帰属が少しでも重要であれば、session JWT モードを使ってください — x-api-key ではなく POST /auth/token で発行します。

session JWT を発行する: `POST /auth/token`

あなたの backend は、プラットフォームの POST /auth/token エンドポイントを呼び出すことで、ユーザーごとに短期の JWT を発行します。認証には API キーを取得するで入手した client_id/client_secret のペアを HTTP Basic 認証として使います。

curl -X POST "https://api.quravin.com/auth/token" \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user-12345",
    "pipelines": ["translate-string"],
    "ttl_seconds": 900
  }'

Response:

{ "token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 900 }

subject（必須）— このユーザーに対するあなたのアプリ側の id です。JWT の sub になります。
pipelines（任意）— このトークンに持たせたい ACL です。ユーザーは、あなたの Application の allowed_pipelines（コンソールで設定、API キーを取得する参照）に載っているパイプラインしか呼び出せません — ここでリクエストした内容はサーバー側でその許可リストと積集合が取られるため、アプリ自体に許可されている以上のものをユーザーに与えることはできません。省略すると、あなたのアプリの許可リスト全体にスコープされたトークンになります。
ttl_seconds（任意）— トークンの有効期間です。60〜3600 秒にクランプされ、デフォルトは 900 （15 分）です。

返された token を sessionToken としてブラウザに渡してください。エンドポイントとブラウザ側の配線の全体、および client_id/client_secret の代わりに個別に払い出された signing secret を使うレガシーな自己署名の代替手段については、自分のサーバーに統合するを参照してください。

これが重要な理由

静的な API キーはベアラー資格情報です — ページのソースからそれを読み取った人は、あなたのアプリができることすべてに完全にアクセスできてしまいます。session JWT は 1 人のユーザーに限定され、数分で期限切れになり、pipelines[] ACL を持ち、ページを読み込むたびにあなたのサーバーが新しく発行します。

経験則： コードがブラウザに配布されるなら、あるいは課金やユーザーごとの帰属が重要であるなら、必要なのは session JWT であり、静的な API キーではありません。

次へ：自分のサーバーに統合するでは、session JWT を発行するトークン発行エンドポイントを紹介します。

認証モードを選ぶ

決定木

x-api-key と session JWT —両者は互換ではない

session JWT を発行する: POST /auth/token

これが重要な理由

`x-api-key` と session JWT —両者は互換ではない

session JWT を発行する: `POST /auth/token`