外部 API 接入快速上手

平台开放 API 支持两种消费方式：**OAuth 2.0 授权码**（代表用户操作）和 **API Key 直连**（服务端调用）。本指南重点介绍小程序、官网等场景下更常用的 API Key 方式。

1. 登录 [开发者门户](/developer) 2. 进入「我的应用」→「注册新应用」 3. 填写应用名称、描述，勾选需要的 Scope（如 `tables:read`、`data:read`） 4. 提交后进入「API Keys」页签，点击「创建 API Key」 5. 复制生成的 `sk-xxx` 密钥，**只显示一次，请妥善保存**

将 API Key 写入你的服务端环境变量（**不要放入客户端代码**）：

```bash APP_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx API_BASE_URL=https://api.sdkok.cn ```

所有请求在 `Authorization` 头携带 API Key：

```typescript const res = await fetch('https://api.sdkok.cn/open/v1/tables/query', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.APP_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ tableId: 'd_MyTableExhibitId', where: [{ field: 'status', op: '=', value: 'active' }], page: 1, pageSize: 20, }), }); const { data } = await res.json(); // data.list → 记录列表, data.total → 总条数 ```

| 端点 | 方法 | 说明 | Scope | |------|------|------|-------| | `/open/v1/tables/query` | POST | 查询智能表数据 | `tables:read` | | `/open/v1/data/:table/query` | POST | 查询业务表数据 | `data:read` | | `/open/v1/ai/chat` | POST | AI 对话（SSE） | `ai:invoke` | | `/open/v1/tools/list` | GET | 获取 AI 工具列表 | `tools:read` | | `/open/v1/tools/invoke` | POST | 调用 AI 工具 | `tools:invoke` |

API 返回标准 JSON，`code: 0` 表示成功；非零或 HTTP 4xx/5xx 表示失败：

```json { "code": 401, "message": "API Key 无效或已过期" } ```

常见错误码：`401` Key 无效、`403` Scope 不足、`429` 触发限流。

API Key 必须存在服务端，禁止在小程序前端代码中硬编码 小程序通过自己的服务端中转调用平台 API（BFF 模式） 建议在 `.env.production` 写入 `APP_API_KEY=sk-xxx`，服务端读取后代理请求

完整 Scope 清单、OAuth 流程和 MCP 接入请查看[开发者文档中心](/developer/docs)。