API 密钥：将其他系统接入您的工作室
API 密钥可让其他系统（如 ERP、自动化表格、网站或您自己的应用）查询和写入工作室的数据，无需人工输入。每个密钥的权限与工作室中的一个用户完全相同，不会超出该用户的权限范围。
- 管理系统需要读取当天的销售数据，以便进行会计处理。
- 自建网站或应用需要登记客户或查询商品目录。
- 自动化流程需要录入支出或查询应收账款。
只有工作室管理员（拥有完整访问权限，或有权编辑个人资料和用户）才能创建、编辑和撤销密钥。如果您无法创建密钥，请联系工作室所有者，在 访问权限 → 个人资料 中为您开通权限。
建议先为集成单独创建一个用户，并为其设置仅开放其他系统所需页面的权限。密钥会继承该用户的权限。
第 1 步 — 打开 API Key 选项卡
Section titled “第 1 步 — 打开 API Key 选项卡”在 设置 → 公司 中，打开 API Key 选项卡。这里会列出已创建的密钥，以及每个密钥对应的用户、允许的 IP、有效期 和 最后使用。
第 2 步 — 创建密钥
Section titled “第 2 步 — 创建密钥”点击 新建密钥，填写 姓名 并选择 用户。在 允许的 IP 中，每行填写一个 IP 地址或 IP 段，只允许来自这些地址的请求（留空则接受任何 IP）。在 有效期 中，选择 永不过期 或 过期时间 并设置日期：密钥在该日期结束前有效。点击 创建密钥，然后使用复制按钮复制密钥。密钥不会再次显示。
其他系统每次发起请求时，都需要在 Authorization 请求头中发送密钥，格式如下：
Authorization: Bearer hk_...（将完整密钥替换 hk_...）。
要在 AI 工具（Claude Code、Gemini CLI、Cursor）中使用此密钥，还需在 AI 连接器 中勾选 允许用作 AI 连接器。如果不启用此选项，密钥可以用于系统集成，但无法用于 AI 连接器。请参阅文章 AI 连接器。
第 3 步 — 撤销密钥
Section titled “第 3 步 — 撤销密钥”在列表中点击密钥旁的垃圾桶图标，并点击 撤销 确认。使用该密钥的系统将在 30 秒内失去访问权限。要修改名称、IP 或有效期，请点击铅笔图标。
- 其他系统使用密钥进行的所有更改，都会以密钥对应用户的名义显示在审计记录中，来源标记为 API 密钥。
- 密钥会在有效期届满或对应用户在工作室中被停用后自动失效。在列表中，密钥会显示为 已过期 或 用户已停用。
- 密钥无法访问其他公司，即使对应用户也在其他公司工作。
常见错误与问题
Section titled “常见错误与问题”问：密钥可以在系统中执行所有操作吗？
**答：**不可以。密钥仅拥有对应用户在本工作室中的权限。有些区域始终不支持使用密钥，即使用户拥有完整访问权限也不例外：登录和切换公司、密钥管理页面本身、用户和邀请管理、Heya、支持服务、仪表板、公司的常规设置（徽标、营业时间、节假日、域名、报告电子邮箱）以及平台页面。如果您有多个集成，请为每个集成单独创建一个用户。审计记录中的更改会显示为对应密钥用户所做。
问：我丢失了密钥，还能再次查看吗？
**答：**不能。系统只保存密钥的摘要，不会保存密钥本身。请撤销旧密钥并创建一个新密钥。
问：其他系统收到“此 IP 未获准使用此 API 密钥。”我该怎么办？
**答：**发起请求的 IP 不在 允许的 IP 中。请编辑密钥并添加该 IP，或将列表留空以接受任何 IP。
问：其他系统收到“此路由不能使用 API 密钥。”这是为什么？
**答：**它正在访问不支持使用密钥的区域（请参阅第一个问题）。这些操作必须由用户在页面中手动完成。
问：可以更改密钥对应的用户吗？
**答：**不可以。请撤销该密钥，并使用新用户创建一个新密钥。
问：新建密钥时，用户列表为空。这是为什么？
**答：**平台团队的用户不能使用 API 密钥，因此不会显示在列表中。请在工作室中创建一个用户（建议专门用于该集成），然后为其创建密钥。