# App Key 创建与管理



## 1. App Key 概述

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

- 所有需要访问开放接口的调用方，都必须先在控制台创建对应的 App Key；
- 请求时通过 HTTP 头 `Authorization: Bearer <AppKey>` 携带；
- App Key 在创建时需要指定**授权范围**，用于决定该 Key 能访问哪些空间的数据，详见 [2.4 授权范围](#_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」对话框中填写以下信息：

    - <b>名称（必填）</b>
        - 用于区分不同用途的 App Key
          示例：
            - `demo`
            - `CRM-外呼接口`
            - `小程序-客服机器人`
        - 支持 **4–30 个字符**。

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

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

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

![](https://avavox.com/docs/appkey/appkey.png)



### 2.4 授权范围

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

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

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

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

调用 [查询 Key 信息](https://avavox.com/docs/developer/bill/key-info.html) 接口可以确认当前 App Key 的授权范围与绑定空间，建议作为对接的第一个调用。各接口在两种授权范围下的具体行为，见 [账单接口总览](https://avavox.com/docs/developer/bill/)。

---

## 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. 检查近期接口调用日志，确认是否存在异常或恶意请求。