選擇您的認證模式

認證 SDK 的兩種方式 — 判斷您需要靜態 API 金鑰還是每位使用者一個的 session JWT 的決策樹。

SDK 支援兩種認證模式。選擇哪一種取決於呼叫 SDK 的程式碼實際在哪裡執行 — 而不是哪一種比較方便。

決策樹

這段程式碼是否在您的伺服器上執行（Node.js backend、cron job、內部服務）？ → API 金鑰模式可用。將您的金鑰以 apiKey 傳入。在 Console 中您 app 的詳細頁面點擊 Regenerate API Key 即可自助產生一把 — 詳見取得您的 API 金鑰，若您不想管理靜態金鑰，也可改用下方的 session JWT 模式。

const ai = new Quravin({
  endpoint: process.env.QURAVIN_URL,
  apiKey:   process.env.QURAVIN_KEY,   // 來自您的 secrets 儲存庫 — 切勿提交進版控
});

這段程式碼是否在使用者的瀏覽器中執行？ → 使用 session JWT 模式。您的伺服器為每位使用者發行短效 token，並傳給頁面 — 瀏覽器永遠看不到 client_secret 或靜態的 API 金鑰。

const ai = new Quravin.Quravin({
  endpoint: "https://api.quravin.com",
  sessionToken: await fetchToken(),   // 來自您自己的 backend endpoint
  onTokenExpired: fetchToken,          // 401 時自動更新
});

`x-api-key` 與 session JWT — 兩者不可互換

上面的 apiKey 會以 x-api-key: <key> 的形式送出請求。這是一種舊式的、app 層級、不綁定 org 的憑證，平台正逐步以每位使用者一個的 JWT 取代它。在使用它之前，有兩件事要先了解：

沒有 org wallet。 如果您的帳號採用 wallet 模式計費，用單純的 x-api-key 認證去呼叫可計費的 POST /tickets，即使 org 的 wallet 有餘額，也會回傳 402 insufficient_credits — 因為這把金鑰沒有綁定任何 org，自然無法從中扣款。這是刻意設計，不是 bug。
沒有每位使用者的身分。 每次呼叫看起來都像是「這個 app」發出的，而不是某個特定使用者 — 這對 cron job 沒問題，但如果您需要每位使用者的稽核／歸因，或需要比整個 app 更細緻的 pipelines[] ACL，就不適用。

只要計費或每位使用者的歸因有任何重要性，就該用 session JWT 模式 — 透過 POST /auth/token 發行，而不是用 x-api-key。如果多個租戶或客戶會共用同一個 backend 行程或憑證，也請改用 session JWT 模式 — 它會把每個呼叫者限定在自己的 ticket 範圍內，x-api-key 則不會。

發行 session JWT：`POST /auth/token`

您的 backend 透過呼叫平台的 POST /auth/token endpoint，並以取得您的 API 金鑰取得的 client_id/client_secret 組合做 HTTP Basic 認證，為每位使用者發行短效 JWT：

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
  }'

回應：

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

subject（必填）— 您 app 對這位使用者的 id；會成為 JWT 的 sub。
pipelines（選填）— 您希望這個 token 擁有的 ACL。使用者只能呼叫您 Application 的 allowed_pipelines（在 Console 設定，見取得您的 API 金鑰）中列出的 pipeline — 這裡請求的內容會在伺服器端與該白名單取交集，所以您無法讓使用者拿到比您 app 本身更多的權限。省略此欄位即可取得涵蓋您 app 全部白名單的 token。
ttl_seconds（選填）— token 存活時間，限制在 60–3600 秒之間，預設 900（15 分鐘）。

把回傳的 token 以 sessionToken 交給瀏覽器。完整的 endpoint 與瀏覽器串接方式，以及使用另外提供的簽章密鑰（而非 client_id/client_secret）的舊式自行簽發替代方案，請參見整合到您自己的伺服器。

為什麼這很重要

靜態 API 金鑰是一種持有即生效的憑證 — 任何從您頁面原始碼讀到它的人，都能完全存取您的應用程式所能做的一切。session JWT 則限定給單一使用者，數分鐘內就會過期，帶有 pipelines[] ACL，並且每次載入頁面時都由您自己的伺服器重新發行。

經驗法則： 如果程式碼會送到瀏覽器執行，或計費／每位使用者的歸因有任何重要性，就需要 session JWT，而不是靜態 API 金鑰。

下一步：整合到您自己的伺服器展示了發行 session JWT 的 token 發行 endpoint。

選擇您的認證模式

決策樹

x-api-key 與 session JWT — 兩者不可互換

發行 session JWT：POST /auth/token

為什麼這很重要

`x-api-key` 與 session JWT — 兩者不可互換

發行 session JWT：`POST /auth/token`