切换主题

App Key 创建与管理 ​

1. App Key 概述 ​

App Key 是接口调用时的身份凭证，用于标识调用方身份并进行校验。

  • 所有需要访问开放接口的调用方，都必须先在控制台创建对应的 App Key；
  • 请求时通过 HTTP 头 Authorization: Bearer <AppKey> 携带；
  • App Key 在创建时需要指定授权范围，用于决定该 Key 能访问哪些空间的数据，详见 2.4 授权范围；
  • 授权范围为「仅当前空间」的 App Key 彼此独立，仅在其所属空间内生效，不会影响其他空间的接口访问与权限配置。

注意：App Key 等价于「接口密码」，请妥善保管，避免泄露。

2. 创建 App Key ​

2.1 控制台菜单路径 ​

控制台菜单路径：

空间管理 → 接口回调 → App Key 管理

2.2 前置条件 ​

  • 账号已开通访问当前空间的权限；
  • 具有「接口回调 / App Key 管理」权限。

2.3 创建步骤 ​

  1. 登录控制台；

  2. 在左侧导航中依次点击：
    空间管理 → 接口回调 → App Key 管理；

  3. 在 App Key 管理 页面右上角，点击 「创建 App Key」；

  4. 在弹出的「创建 App Key」对话框中填写以下信息：

    • 名称（必填）

      • 用于区分不同用途的 App Key 示例：
        • demo
        • CRM-外呼接口
        • 小程序-客服机器人
      • 支持 4–30 个字符。

    • 账单查询范围（必填）

      • 本企业全部空间：该 Key 可访问企业下所有空间的数据。选择此项需要当前登录人具备企业管理员权限。
      • 仅当前空间：该 Key 绑定当前空间，只能访问该空间的数据。无前置条件。
      • 授权范围创建后不可变更，需要调整请重新创建 App Key。

  5. 确认无误后点击 「确定」 完成创建。

创建成功后，系统会生成一条新的 App Key 记录，并显示在列表中。

2.4 授权范围 ​

授权范围决定了 App Key 的数据可见边界。两种范围的鉴权方式完全相同，区别只在于能看到哪些空间的数据：

授权范围数据可见范围典型使用方
本企业全部空间企业下全部空间企业财务 / BI 系统
仅当前空间仅创建时所在的那一个空间各业务团队

通常只需要一把 Key

「本企业全部空间」是「仅当前空间」的超集，一把企业级 Key 即可覆盖全部查询场景。只有在需要按团队隔离数据（把 Key 分发给各空间自行使用）时，才需要签发多把「仅当前空间」的 Key。

越权参数会直接报错

当 Key 的授权范围为「仅当前空间」，而请求参数中指定了其他空间时，接口会直接返回失败，而不是静默剔除该空间。这样可以避免你误以为拿到的是多空间合计数据。

调用 查询 Key 信息 接口可以确认当前 App Key 的授权范围与绑定空间，建议作为对接的第一个调用。各接口在两种授权范围下的具体行为，见 账单接口总览。

3. 查看与使用 App Key ​

3.1 查看与复制 ​

  1. 返回 App Key 管理 页面；

  2. 在列表中找到刚创建的记录，可看到以下字段：

    • 名称
    • App Key（以 sk- 开头，中间部分可能做脱敏展示）
    • 账单查询范围（本企业全部空间 / 仅当前空间）
    • 最近使用时间
    • 创建时间
    • 状态（启用 / 禁用）

  3. 点击 App Key 字段右侧的 复制图标，即可复制完整的 App Key，用于配置到你的应用中。

3.2 接口调用中的使用方式 ​

所有需要鉴权的接口请求头中，需携带以下字段：

shell
Authorization: Bearer <Your-App-Key>
Content-Type: application/json

其中 <Your-App-Key> 替换为在控制台获取到的实际 App Key。

示例（curl）

shell
curl -X GET "https://dashboard.avavox.com/open/api/task/robot" \
  -H "Authorization: Bearer sk-xxxxxxx" \
  -H "Content-Type: application/json"

4. App Key 管理与安全策略 ​

4.1 状态管理：启用 / 禁用 ​

在 App Key 管理 页面，可对已有 App Key 进行状态控制：

  • 启用：当前 App Key 可正常用于接口调用；
  • 禁用：当前 App Key 将无法通过鉴权，所有使用该 Key 的请求都会失败。

操作步骤 ​

  1. 在目标 App Key 所在行的「操作」列中点击 「禁用」；
  2. 在弹窗中确认后，该 App Key 将变为 已禁用 状态；
  3. 若需恢复使用，在同一位置点击 「启用」 即可重新启用。

典型场景 ​

  • 某应用临时停用接口能力；
  • 怀疑 App Key 被外泄，需要快速阻断调用。

4.2 删除 App Key ​

如果确认某个 App Key 不再使用，可以选择删除：

  1. 在目标 App Key 所在行的「操作」列中点击 「删除」；
  2. 在弹出的确认提示中点击 确定，执行删除操作。

⚠️ 注意 ​

  • 删除为不可恢复操作；
  • 删除后，所有使用该 App Key 的接口调用将立即失败；
  • 若存在不确定性，建议优先使用「禁用」而非直接删除。

5. 常见问题（FAQ） ​

Q1：一个应用可以使用多个 App Key 吗？ ​

可以。建议按「不同环境（测试 / 生产）」或「不同业务」划分 App Key，以方便隔离与追踪和权限控制。

Q2：App Key 泄露怎么办？ ​

建议操作顺序如下：

  1. 立即创建新的 App Key，并更新到应用配置中；
  2. 在控制台中禁用或删除旧的 App Key；
  3. 检查近期接口调用日志，确认是否存在异常或恶意请求。