Skip to content

API 鉴权 ​

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

以前在「数据 API」页创建的 OpenAPI Key(组织 Key)仍可用于部分存量接口。

创建个人 API Key ​

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

超级管理员设置组织权限 ​

在目标组织进入「全局设置 → 安全与追溯 → API Key 管理 → 组织策略」。只有超级管理员能看到「组织策略」和「组织内全部」两个视图。直接打开组织策略

  1. 在「最高权限」选择组织允许的最高档位,点「保存」。放宽权限时还需在弹窗确认。这里同时约束该组织的个人 API Key 和 MCP 的 OAuth 授权。
  2. 在同页设置「允许高级成员创建个人 API Key」。这个开关单独控制高级成员的创建资格,切换后立即保存。
最高权限在成员已有资源权限内可以做什么
只读查询码、表单、填写记录和指标。适合报表同步。
读写还可新建二维码、模板和表单,修改通过接口创建且支持编辑的内容。适合自动建巡检码。
完全还可修改成员手工创建且支持编辑的内容,并调用支持的删除接口。删除前需预览并确认具体对象。

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

验证 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 调用它不支持的接口,换成个人 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

代码示例 ​

bash
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
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
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

$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「草料扫码器」小程序
管理端 MCPOAuth 授权,不需要 Key客户端连接时授权
扫码端 MCP、A2A不需要—