API Key 与公开 API
创建最小权限公开 API Key，完成第一次读取，并安全处理限流或送达不确定。
- 适用对象
- 管理员
- 内容更新
- 2026-09-09
先登录公司系统；文中的 /app/… 是加在公司系统网址后的页面路径。
开始前
- 管理员账号，以及已登录的你自己的部署域名
- 公开 API 运行时开关已启用；池化部署还需要 Max 或 Enterprise 权益
- 已有接入来源，或“创建或管理接入来源”的权限
操作步骤
打开正确指南并选择来源
打开你自己的部署域名下的 /app/int/docs?section=api&lang=zh 或 /app/int/docs?section=api&lang=en。在“开发者中心 → API 密钥”使用现有来源选择器；没有来源时选择“创建或管理接入来源”，先完成来源设置。默认 /app/int/docs 仍是旧版导入指南。
预期结果: 你是在为目标来源配置公开 API，而不是误用旧版导入路径。
签发最小权限密钥
密钥管理仅限管理员。此工作区签发的密钥会明确启用公开 API；请先使用最小权限 customers.read，只增加工作所需 scope。团队或收件箱限制为空，表示该维度不再额外收窄；既有 scope 与租户边界仍然适用。旧版导入密钥不会自动获得公开 API 权限。
预期结果: 密钥只能读取目标租户及范围内的数据。
复制并保护密钥
密钥只显示一次，请复制后保存到受保护的服务端配置。不要嵌入公开网页的应用代码、URL、截图或日志。publicApi true 不会把密钥与导入隔离；customers.write 也可能授权导入。密钥泄露时立即撤销，再按最小权限原则签发替代密钥。
预期结果: 密钥有明确的安全保存与撤销恢复路径。
完成第一次只读请求
签发只读密钥后，点击“验证只读请求”，使用该密钥调用页面展示的不带资源 ID 路径参数的 GET，并检查真实返回的 data 和 meta。也可以复制与权限匹配的请求到服务端终端执行；公开 API 参考提供请求和响应示例。保存后请隐藏密钥。
预期结果: 第一次真实响应确认密钥可用，并展示它能访问的资源。
分页读取并遵守限流
分页默认 50 条、最多 100 条；持续传入 meta.nextCursor，直到它为 null。以运行时配置和限流响应头为准：默认每个 Key 每分钟 60 次、每租户每分钟 600 次。收到 429 时遵守 Retry-After。ID 是字符串，时间是 UTC ISO。
预期结果: 客户端能从游标继续读取，并遵守当前部署的限流。
安全发送并核对送达
文本发送需要 8–64 字符的 Idempotency-Key，同一请求重试沿用同一个值。accepted 或 queued 只表示已接受处理，不表示渠道已送达；请检查消息状态或 Webhook。不要自动执行写入测试；可选“验证只读请求”只执行不带资源 ID 路径参数的 GET。
预期结果: 重试有边界且不会重复发送，也不会把“已接受”误当成已送达。