驗證

每個 API 請求都要在 Authorization 標頭裡帶一把 API 金鑰：

Authorization: Bearer sk-popnow-3f9c0a…

沒有其他驗證方式：放在網址查詢參數裡的金鑰一律不接受，你在 popnow.ai 網站的登入狀態在 API 上也無效。

只有一個例外：/v1 下的 OpenAI 相容介面 也認 x-api-key 請求標頭裡的金鑰，OpenAI 風格的用戶端不用改。原生 /api/v1 介面只認 Authorization。

金鑰長什麼樣子

金鑰是 sk-popnow- 加上 48 個小寫十六進位字元。建立之後，API 控制台只會顯示開頭幾碼，所以遺失的金鑰無法找回——再建立一把新的就好。

建立金鑰

1. 登入 popnow.ai，開啟 API 控制台。
2. 點選 Create key，取一個能說明用途的名稱，例如 production-backend。
3. 立刻複製。完整的金鑰只會顯示這一次。

一個帳戶可以同時擁有多把金鑰。建議每個環境、每個服務各用一把，撤銷其中一把時就不會影響其他的。所有金鑰共用同一個點數餘額。

金鑰該放哪裡

• 放進環境變數或平台的機密管理（POPNOW_API_KEY），不要寫進原始碼。
• 絕對不要放進瀏覽器、手機 App 或任何在別人裝置上執行的程式碼。能讀到金鑰的人就能花你的點數。讓你自己的伺服器擋在中間，由它呼叫 PopNow。
• 不要寫進記錄檔。如果會記錄請求標頭，請先移除 Authorization。

限制金鑰能做什麼

每把金鑰都可以在 API 控制台個別設定限制：

預設情況下金鑰沒有任何限制，也沒有上限。正式環境的金鑰，給到夠用的最小範圍即可。

任務屬於建立它的那把金鑰

recordInfo、retry、purge、任務清單與用量，都只看得到同一把金鑰建立的任務。帳戶中另一把金鑰建立的任務會回傳 404，和不存在的任務完全相同。你在網站上發起的生成，任何金鑰也都看不到。要看整個帳戶的情況，請使用 API 控制台。

輪替

不中斷服務地替換金鑰：

1. 建立新金鑰。
2. 把它部署到所有使用舊金鑰的地方。
3. 在控制台確認舊金鑰的「最近使用時間」不再變動。
4. 撤銷舊金鑰。

金鑰外洩時

1. 立刻撤銷：在 API 控制台操作，下一個請求起就生效。
2. 換上新金鑰並部署。
3. 查看它被拿來做了什麼：控制台的記錄與用量會列出這把金鑰建立的每個任務。
4. 收緊新金鑰的權限：加上 IP 允許清單與消費上限。

如果發現不是你發起的消費，請聯絡客服。

失敗時的樣子

三種驗證問題都回傳 HTTP 401、code: 401，靠 msg 區分：

金鑰有效也可能被 403 拒絕，例如帳戶的電子郵件尚未驗證（40310）。請見錯誤碼。