API 密钥管理

当您需要通过代码/接口的方式与 JoyInside 平台交互(如设备自动注册、发起对话等)时,需要使用 API 密钥来验证身份。

1. 页面字段说明

字段	说明
名称	密钥对的名称,方便识别
Access Key	访问密钥标识(相当于「用户名」)
Secret Key	访问密钥密码(相当于「密码」,请妥善保管)
创建时间	密钥创建时间
接口根地址	所有 API 请求的基础地址,当前值为 https://api.joyinside.com/

接口根地址

所有 API 请求的基础地址为 https://api.joyinside.com/,以平台页面显示的值为准。

2. 使用限制

• 一个企业只能创建一个密钥对(不支持多套密钥并行)
• 密钥对支持编辑和删除

为什么每企业只有一对

API 密钥是企业级凭证,统一发放便于账号级别的追踪和安全管控。若需要多环境隔离(测试/生产),建议在业务侧做环境隔离,而非在平台侧多开密钥。

3. 如何调用

3.1 认证方式

请求需在 Header 中携带鉴权信息(具体签名算法以平台接口文档为准):

Authorization: <signature-based-on-access-key-and-secret-key>
Host: api.joyinside.com

3.2 常见调用场景

场景	调用主体	说明
设备自动注册	品牌方后端/设备端	硬件首次联网时,携带 API 密钥调用注册接口,把设备登记到 设备管理
发起对话	品牌方后端/设备端	使用设备 ID + API 密钥调用对话接口
数据查询/管理接口	品牌方后端	查询设备状态、拉取对话记录等(以接口文档为准)

3.3 接口文档入口

点击页面中的「查看文档」可跳转到完整的 API 说明文档。

4. 注意事项

1. Secret Key 请妥善保管:它相当于您企业账号的密码,泄露后他人可以调用您的接口;
2. 不要把密钥硬编码进设备端固件:建议通过服务端签名后再下发到设备,避免逆向抓取;
3. 密钥泄露立即处置:删除旧密钥 → 重新创建 → 更新所有已上线服务的配置;
4. 接口根地址:https://api.joyinside.com/,以平台页面显示的值为准。

5. 常见 Q&A

Q1:一个企业内的多个团队/产品线,如何隔离权限?

A:目前平台侧一个企业只有一对密钥,建议在企业内部网关做团队级鉴权,或按产品线拆分企业账号。

Q2:密钥丢了怎么办?

A:Access Key 可以在平台页面查看,但 Secret Key 一旦丢失无法找回,需要删除现有密钥对并重新创建。重建后需同步更新所有已上线服务的配置。

Q3:接口调用失败,401 Unauthorized 怎么排查?

A:按优先级检查:

1. Access Key / Secret Key 是否复制正确、是否有多余空格;
2. 签名算法是否与接口文档一致(时间戳、Nonce、字段顺序);
3. 接口根地址是否为 https://api.joyinside.com/(见 §1 页面字段说明);
4. 密钥是否已被删除或替换。

6. 相关链接

• 开发者中心总览
• 第三方服务管理 — 让平台按 A2A 协议调用你的外部 Agent
• 设备管理 — 用 API 密钥自动注册设备