开发者 API

开发者标签页是你颁发 API 密钥以编程方式访问 Entergram 的入口。需要 Pro 套餐（以及 Pro 工作区席位）。仅所有者和管理员可用。

创建密钥

1. 「创建 API 密钥」
2. 命名（取一个你日后在撤销列表中能认出的名字）
3. 选择 scope——细粒度权限，例如：
   • workspace.read
   • members.read
   • accounts.read
   • contacts.read
   • chats.read / chats.write
   • custom_fields.read / custom_fields.write
4. 默认 TTL 为 90 天；你可以选择更短的时长
5. 可选：限制为某些 IP CIDR 段
6. 点击创建——完整密钥仅显示一次。请立即复制；Entergram 不会再次显示它。

内部机制

• 密钥以单向哈希方式存储——原始密钥从不落盘
• 每次请求都会记录前缀、IP 和 user agent 以供审计
• 撤销立即生效
• 过期密钥自动返回 403
• 每次 API 调用都被限定在工作区内——某个密钥只能在颁发它的工作区中操作

管理密钥

在开发者标签页中：

• 查看每个密钥的前缀、创建日期、scope、TTL 和最近使用信息
• 复制前缀（不复制密钥本身）
• 撤销或轮换密钥
• 轮换 = 创建一个具有相同 scope 的新密钥，待集成切换完成后再撤销旧密钥

示例：轮换泄露的密钥

1. 你发现某位工程师将密钥粘贴到了公开的 issue 跟踪器中
2. 开发者标签页 → 找到该密钥 → 撤销（立即生效）
3. 创建一个具有相同 scope 和 IP 白名单的新密钥
4. 将新密钥部署到你的集成中
5. 检查旧密钥的最近使用信息以确认不再有流量

示例：为 CI 任务签发密钥

1. 开发者标签页 → 创建 API 密钥
2. 命名为 ci-deploy-bot
3. Scope：仅 workspace.read 和 chats.read（最小权限）
4. TTL：30 天
5. IP 白名单：CI 服务商的出口 IP
6. 复制密钥并将其设置为 CI 中的 secret
7. 在 TTL 到期前进行轮换

Make.com 集成

Pro 套餐包含 Make.com 集成，让你无需自行编写 API 代码即可将 Entergram 接入低代码自动化流程。可在工作区集成区域使用。

API 响应

你将看到的常见 HTTP 错误：

• 401——密钥已过期、被撤销，或与该工作区不匹配
• 403——密钥缺少所需的 scope，或请求来自白名单之外的 IP
• 429——你已触发限速；请退避后重试