API Authentication
Use a personal API key to call the V2 API. The key is tied to the member who created it and to one organization, and it can reach the same projects and resources that member can in the console. Use an OAuth access token instead when a third-party application needs each user to pick an organization and grant access. Send either one in the Authorization: Bearer <token> header.
OpenAPI Keys created earlier on the Data API page (organization keys) still work for a fixed set of existing endpoints.
Create a personal API key
- Sign in to the admin console and switch to the organization your application will access. Open Settings → Security and audit → API Key management → My keys (全局设置 → 安全与追溯 → API Key 管理 → 我的 Key). Once the feature is available to the organization, super administrators can create keys. Advanced members can create them if organization policy allows it. Open API Key management
- Select Create personal API key (创建个人 API Key). Name it for its purpose, such as “Inspection report sync”. Select Read only for reports or Read/write to create codes and forms. See Full below for editing manually created content or deleting resources.
- Choose 30 days, 90 days (default), one year or no expiry. Select Create (创建), then Copy (复制). Store the key in your application's credential configuration before selecting I have saved it (我已保存). The list displays only the last characters of the key.
Set organization permissions as a super administrator
In the target organization, open Settings → Security and audit → API Key management → Organization policy (组织策略). Only super administrators see Organization policy and All organization keys (组织内全部). Open organization policy
- Under Maximum permission (最高权限), select the highest level the organization allows and select Save (保存). Confirm any increase. The ceiling applies to both personal API keys and MCP OAuth grants.
- Set Allow advanced members to create personal API keys (允许高级成员创建个人 API Key) on the same page. This switch controls who may create a key. Changes to the switch are saved immediately.
| Level | Operations within the member's existing resource permissions |
|---|---|
| Read only | Read codes, forms, submitted records and metrics. Use for reporting. |
| Read/write | Also create codes, templates and forms, and edit supported content created through the API or MCP. Use for automated code creation. |
| Full | Also edit supported content created manually by members and use supported deletion endpoints. Preview and confirm the items before deletion. |
For example, lowering the organization ceiling to Read only limits an existing Full key to reads. Raising the ceiling to Read/write leaves an existing Read only key at Read only. Create a key at the new level or repeat MCP OAuth authorization and select the required level. The member's access to projects and resources still applies.
Verify a key and troubleshoot permissions
Set the local environment variable CAOLIAO_API_KEY to your personal key. This read-only call shows the organization and effective permissions associated with the credential.
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 '{}'| Symptom | What to check |
|---|---|
| Organization policy is missing or Create is disabled | Check the selected organization and your role. Advanced members can ask a super administrator to check the creation switch. The page explains why creation is unavailable. |
| A permission level is unavailable | Check Maximum permission under Organization policy. A new key cannot exceed the ceiling. |
| HTTP 401 | Check the Bearer header and the key's expiry and revocation status under My keys. |
| Reads work but edits or deletions return HTTP 403 | Check the organization ceiling, the key or OAuth grant level, and access to the target resource. |
HTTP 403 credential_type_not_allowed | You are calling an endpoint that organization keys cannot use. Switch to a personal key. |
Replace or revoke a key. A key's permission level is fixed at creation. Create a replacement, switch your application to it and verify access before revoking the previous key under My keys. Super administrators can also revoke member keys under All organization keys. Revocation takes effect immediately and is permanent.
Legacy organization keys
An OpenAPI Key created under Data Management → Data API is an organization key. It is not tied to a member and covers the whole organization. Existing integrations keep working; use a personal key for anything new. An organization key can call only:
| Area | Endpoints |
|---|---|
| Codes | qrcodes/list, qrcodes/getContent, qrcodes/getOperation |
| Batch templates and sub-codes | templates/list, templates/get, templates/listQrcodes, templates/getSubcode |
| Forms and records | record/getFormList, forms/getTemplate, record/getRecord, record/getRecords, record/searchRecords, record/addRecord, certificates/verify |
| Metrics and organization | metrics/list, metrics/get, metrics/query, projects/list |
| Credential and quota | auth/getContext, usage/get |
| v1 APIs | Every /api/v1/ endpoint. v1 accepts organization keys only, does not accept personal keys, and is no longer updated |
Calling any other V2 endpoint with an organization key (the management endpoints for creating, editing, deleting and exporting labels) returns HTTP 403 with the error code credential_type_not_allowed. V2 endpoints added in the future accept personal keys and OAuth only.
Send the key in a request
Add an Authorization field to the request header with the value Bearer <API Key>. Personal keys start with clk_. For example, if your key is clk_Abc123456, the header is:
Authorization: Bearer clk_Abc123456Code examples
curl -X POST 'https://open.cli.im/api/v2/rpc/qrcodes/list' \
-H 'Authorization: Bearer <YourAPIKey>' \
-H 'Content-Type: application/json' \
-d '{"page_size": 20}'import requests
url = "https://open.cli.im/api/v2/rpc/qrcodes/list"
headers = {
"Authorization": "Bearer <YourAPIKey>", # Replace with your 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 <YourAPIKey>") // Replace with your 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 <YourAPIKey>', // Replace with your 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);Authentication for other capabilities
This key is only for the APIs in the API Reference. Other capabilities use their own methods:
| Capability | Authentication | Where to get it |
|---|---|---|
| V2 API | Personal API key or OAuth; some existing endpoints also accept a legacy organization key | This page |
| v1 APIs (no longer updated) | Organization key | Data Management → Data API in the console |
| QR code image tools | None | — |
| Label Generation · public styles | No key; pass the public style ID | Label design library |
| Label Generation · private styles | api_key and sign signature in request parameters | "API对接" (API Integration) on the label style's detail page |
| CaoLiao Scanner skill package | Login by scan, or a Scanner API Key | The CaoLiao Scanner WeChat Mini Program |
| Admin MCP | OAuth authorization, no key | Authorize when the client connects |
| Scan-side MCP, A2A | None | — |