For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/api.md (or send Accept: text/markdown).

公開 API、金鑰與 webhook

客戶在其上構建的版本化 REST 介面。

詢問本指南

開始之前

使用“檔案”→“開啟資料夾”在 Visual Studio Code 中開啟下載的 supastack 專案，然後選擇“終端”→“新建終端”。儲存庫根目錄是包含 package.json、apps 和 packages 的資料夾。執行下面的命令並保持終端開啟。如果無法識別命令，請先完成工具安裝指南，然後再繼續。

首先閱讀平臺教程。伺服器是響應瀏覽器或電話請求的應用程式程式。 Web 讀取 apps/web/.env.local，Expo 讀取 apps/mobile/.env.local，資料庫遷移命令讀取 root .env。無資料庫/儀錶板演示與真實/身份驗證帳戶分開，需要遷移Postgres。僅電話或桌面結帳需要單獨執行的 Web 後端。

corepack pnpm --filter @supastack/web dev

安裝與配置

packages/api 定義版本化契約:每個請求和響應的 zod 模式、錯誤信封,以及在 /api/v1/openapi 提供並在 /api/docs 渲染的 OpenAPI 檔案。工作區 API 金鑰在設定 → 開發者中建立;明文只顯示一次,之後只保留雜湊後的金鑰。

金鑰帶有字首(sk_<env>_…)、作用域(預設讀取),並在每個請求中解析到工作區。出站 webhook 訂閱在同一開發者介面管理。

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

實現流程

使用 Bearer 金鑰認證;伺服器從金鑰解析工作區,絕不使用客戶端提供的 id。保持響應形狀版本化 —— v1 內只做增量變更,破壞性變更放在新版本之後。

對於出站 webhook,將端點 URL 訂閱到事件目錄;投遞經過簽名並記錄,消費者可以驗證並重放。目錄使用 webhook-events.ts,投遞嘗試使用 webhook-delivery.ts。

驗證與排障

驗證已吊銷的金鑰返回 401、作用域不足的金鑰被拒絕,以及 OpenAPI 檔案可以解析。對於 webhook,測試簽名驗證、失敗後的重新投遞,以及事件負載絕不攜帶提供商金鑰。