# API 鉴权

调用 V2 接口默认使用个人 API Key：它绑定创建它的成员和组织，能访问的分区和资源与这位成员在后台看到的一致。第三方应用需要用户自己选择组织并授权时，改用 OAuth access token。两者都通过 `Authorization: Bearer <token>` 发送。

以前在「数据 API」页创建的 OpenAPI Key（组织 Key）仍可用于[部分存量接口](https://cli.im/open-api/openapi/v2/auth.html#org-key)。

## 创建个人 API Key {#create-key}

1. 登录草料二维码管理后台，切换到脚本要访问的组织。在「全局设置 → 安全与追溯 → API Key 管理」打开「我的 Key」。超级管理员可以创建；高级成员需要组织已开通此能力，且管理员允许高级成员创建。[打开 API Key 管理](https://console.cli.im/setting/personalApiKey)
2. 点「创建个人 API Key」，用用途命名，例如“巡检报表同步”。只查报表选「只读」，需要新建巡检码和表单选「读写」。需要编辑成员手工创建的内容或删除时，再核对下表中的「完全」权限。
3. 选择有效期，可选 30 天、90 天、1 年或永久，默认 90 天。点「创建」，在成功弹窗中点「复制」，保存到应用的凭证配置后再点「我已保存」。列表只显示尾号，关闭弹窗后无法再次查看完整 Key。

## 超级管理员设置组织权限 {#org-policy}

在目标组织进入「全局设置 → 安全与追溯 → API Key 管理 → 组织策略」。只有超级管理员能看到「组织策略」和「组织内全部」两个视图。[直接打开组织策略](https://console.cli.im/setting/personalApiKey?view=policy)

1. 在「最高权限」选择组织允许的最高档位，点「保存」。放宽权限时还需在弹窗确认。这里同时约束该组织的个人 API Key 和 MCP 的 OAuth 授权。
2. 在同页设置「允许高级成员创建个人 API Key」。这个开关单独控制高级成员的创建资格，切换后立即保存。

| 最高权限 | 在成员已有资源权限内可以做什么 |
|---|---|
| 只读 | 查询码、表单、填写记录和指标。适合报表同步。 |
| 读写 | 还可新建二维码、模板和表单，修改通过接口创建且支持编辑的内容。适合自动建巡检码。 |
| 完全 | 还可修改成员手工创建且支持编辑的内容，并调用支持的删除接口。删除前需预览并确认具体对象。 |

例如，个人 Key 选了「完全」，后来组织上限调为「只读」，该 Key 只能读取。反过来，把组织上限从「只读」调到「读写」，原先的只读 Key 仍然只读。使用个人 Key 时需新建相应档位的 Key；使用 MCP 时需重新授权并选择相应档位。成员可访问的分区和资源范围仍然生效。

## 验证 Key、排查权限 {#verify-key}

将个人 Key 放在本机环境变量 `CAOLIAO_API_KEY`，用下面的只读请求查看凭证对应的组织和有效权限。

```bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/auth/getContext' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

| 遇到的情况 | 检查位置 |
|---|---|
| 看不到「组织策略」，或创建按钮不可用 | 确认当前组织和成员身份。高级成员可请超级管理员检查创建开关；创建按钮旁会提示当前账号受限的原因。 |
| 创建时某档权限不可选 | 到「组织策略」核对「最高权限」。新 Key 的档位不能超过组织上限。 |
| 调用返回 401 | 检查 Bearer 请求头，以及「我的 Key」中的有效期与撤销状态。 |
| 可以查数据，但编辑或删除返回 403 | 依次核对组织上限、Key 或 OAuth 的授权档位、成员对目标资源的管理权限。 |
| 返回 403 `credential_type_not_allowed` | 正在用组织 Key 调用[它不支持的接口](https://cli.im/open-api/openapi/v2/auth.html#org-key)，换成个人 Key。 |

**更换或撤销 Key。** 创建后不能直接修改 Key 的权限。需要换档或替换凭证时，先创建新 Key，更新应用并验证，再在「我的 Key」中撤销旧 Key。超级管理员可以在「组织内全部」中找到成员的 Key 并撤销。确认撤销后立即失效，无法恢复。

## 历史组织 Key {#org-key}

在后台「数据管理 → 数据 API」页创建的 OpenAPI Key 是组织 Key：不绑定成员，数据范围是整个组织。已经在用的集成不用改，新接入请用个人 Key。组织 Key 可以调用的范围固定为：

| 范围 | 接口 |
|---|---|
| 码 | `qrcodes/list`、`qrcodes/getContent`、`qrcodes/getOperation` |
| 批量模板与子码 | `templates/list`、`templates/get`、`templates/listQrcodes`、`templates/getSubcode` |
| 表单与记录 | `record/getFormList`、`forms/getTemplate`、`record/getRecord`、`record/getRecords`、`record/searchRecords`、`record/addRecord`、`certificates/verify` |
| 指标与组织 | `metrics/list`、`metrics/get`、`metrics/query`、`projects/list` |
| 凭证与额度 | `auth/getContext`、`usage/get` |
| v1 接口 | 全部 `/api/v1/` 接口。v1 只接受组织 Key，不支持个人 Key，且[不再更新](https://cli.im/open-api/openapi/migrate-from-v1.md) |

用组织 Key 调用表外的 V2 接口（生成二维码、编辑、删除、标签导出等[管理接口](https://cli.im/open-api/openapi/v2/management.md)）返回 HTTP 403，错误码 `credential_type_not_allowed`。以后新增的 V2 接口也只支持个人 Key 和 OAuth。

## 在请求中携带 Key

在请求头（Header）中添加 `Authorization` 字段，值为 `Bearer <API Key>`。个人 Key 以 `clk_` 开头，例如 Key 为 `clk_Abc123456`，则携带的 Header 为：

```
Authorization: Bearer clk_Abc123456
```

### 代码示例

:::code-group

```bash [curl]
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/list' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"page_size": 20}'
```

```python [Python + requests]
import requests

url = "https://open.cli.im/api/v2/rpc/qrcodes/list"
headers = {
    "Authorization": "Bearer <你的API Key>",  # 替换为你的 API Key
    "Content-Type": "application/json"
}

response = requests.post(url, json={"page_size": 20}, headers=headers)
print(response.text)
```

```java [Java + HttpClient]
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

public class ListQrcodes {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://open.cli.im/api/v2/rpc/qrcodes/list"))
                .header("Authorization", "Bearer <你的API Key>") // 替换为你的 API Key
                .header("Content-Type", "application/json")
                .POST(BodyPublishers.ofString("{\"page_size\": 20}"))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```php [PHP]
<?php

$ch = curl_init('https://open.cli.im/api/v2/rpc/qrcodes/list');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的API Key>', // 替换为你的 API Key
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['page_size' => 20]));

echo curl_exec($ch);
curl_close($ch);
```



## 其他能力的鉴权方式

个人 Key 用于 V2 接口。其他能力用各自的方式：

| 能力 | 鉴权方式 | 从哪获取 |
|---|---|---|
| V2 接口 | 个人 Key 或 OAuth；[部分存量接口](https://cli.im/open-api/openapi/v2/auth.html#org-key)也接受历史组织 Key | 本页 |
| v1 接口（不再更新） | 组织 Key | 后台「数据管理 → 数据 API」 |
| [二维码图片工具](https://cli.im/open-api/qrcode-api/quick-start.md) | 不需要 | — |
| [标签生成 API · 公共样式](https://cli.im/open-api/label-api/public-style-label.md) | 不需要 Key，传公共样式编号 | [标签样式库](https://cli.im/label) |
| [标签生成 API · 私有样式](https://cli.im/open-api/label-api/private-style-label.md) | 请求参数带 `api_key` 和 `sign` 签名 | 标签样式详情页的「API对接」 |
| [草料扫码器技能包](https://cli.im/open-api/deepscan/skills.md#api-key) | 扫码登录，或扫码器 API Key | 「草料扫码器」小程序 |
| [管理端 MCP](https://cli.im/open-api/agent/open-platform-mcp.md) | OAuth 授权，不需要 Key | 客户端连接时授权 |
| [扫码端 MCP、A2A](https://cli.im/open-api/agent/overview.md) | 不需要 | — |
