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/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,测试签名验证、失败后的重新投递,以及事件负载绝不携带提供商密钥。