API 鉴权
调用 V2 接口默认使用个人 API Key:它绑定创建它的成员和组织,能访问的分区和资源与这位成员在后台看到的一致。第三方应用需要用户自己选择组织并授权时,改用 OAuth access token。两者都通过 Authorization: Bearer <token> 发送。
以前在「数据 API」页创建的 OpenAPI Key(组织 Key)仍可用于部分存量接口。
创建个人 API Key
- 登录草料二维码管理后台,切换到脚本要访问的组织。在「全局设置 → 安全与追溯 → API Key 管理」打开「我的 Key」。超级管理员可以创建;高级成员需要组织已开通此能力,且管理员允许高级成员创建。打开 API Key 管理
- 点「创建个人 API Key」,用用途命名,例如“巡检报表同步”。只查报表选「只读」,需要新建巡检码和表单选「读写」。需要编辑成员手工创建的内容或删除时,再核对下表中的「完全」权限。
- 选择有效期,可选 30 天、90 天、1 年或永久,默认 90 天。点「创建」,在成功弹窗中点「复制」,保存到应用的凭证配置后再点「我已保存」。列表只显示尾号,关闭弹窗后无法再次查看完整 Key。
超级管理员设置组织权限
在目标组织进入「全局设置 → 安全与追溯 → API Key 管理 → 组织策略」。只有超级管理员能看到「组织策略」和「组织内全部」两个视图。直接打开组织策略
- 在「最高权限」选择组织允许的最高档位,点「保存」。放宽权限时还需在弹窗确认。这里同时约束该组织的个人 API Key 和 MCP 的 OAuth 授权。
- 在同页设置「允许高级成员创建个人 API Key」。这个开关单独控制高级成员的创建资格,切换后立即保存。
| 最高权限 | 在成员已有资源权限内可以做什么 |
|---|---|
| 只读 | 查询码、表单、填写记录和指标。适合报表同步。 |
| 读写 | 还可新建二维码、模板和表单,修改通过接口创建且支持编辑的内容。适合自动建巡检码。 |
| 完全 | 还可修改成员手工创建且支持编辑的内容,并调用支持的删除接口。删除前需预览并确认具体对象。 |
例如,个人 Key 选了「完全」,后来组织上限调为「只读」,该 Key 只能读取。反过来,把组织上限从「只读」调到「读写」,原先的只读 Key 仍然只读。使用个人 Key 时需新建相应档位的 Key;使用 MCP 时需重新授权并选择相应档位。成员可访问的分区和资源范围仍然生效。
验证 Key、排查权限
将个人 Key 放在本机环境变量 CAOLIAO_API_KEY,用下面的只读请求查看凭证对应的组织和有效权限。
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 调用它不支持的接口,换成个人 Key。 |
更换或撤销 Key。 创建后不能直接修改 Key 的权限。需要换档或替换凭证时,先创建新 Key,更新应用并验证,再在「我的 Key」中撤销旧 Key。超级管理员可以在「组织内全部」中找到成员的 Key 并撤销。确认撤销后立即失效,无法恢复。
历史组织 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,且不再更新 |
用组织 Key 调用表外的 V2 接口(生成二维码、编辑、删除、标签导出等管理接口)返回 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代码示例
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}'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)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
$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;部分存量接口也接受历史组织 Key | 本页 |
| v1 接口(不再更新) | 组织 Key | 后台「数据管理 → 数据 API」 |
| 二维码图片工具 | 不需要 | — |
| 标签生成 API · 公共样式 | 不需要 Key,传公共样式编号 | 标签样式库 |
| 标签生成 API · 私有样式 | 请求参数带 api_key 和 sign 签名 | 标签样式详情页的「API对接」 |
| 草料扫码器技能包 | 扫码登录,或扫码器 API Key | 「草料扫码器」小程序 |
| 管理端 MCP | OAuth 授权,不需要 Key | 客户端连接时授权 |
| 扫码端 MCP、A2A | 不需要 | — |