Skip to content

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 ​

  1. 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
  2. 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.
  3. 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

  1. 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.
  2. 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.
LevelOperations within the member's existing resource permissions
Read onlyRead codes, forms, submitted records and metrics. Use for reporting.
Read/writeAlso create codes, templates and forms, and edit supported content created through the API or MCP. Use for automated code creation.
FullAlso 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.

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 '{}'
SymptomWhat to check
Organization policy is missing or Create is disabledCheck 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 unavailableCheck Maximum permission under Organization policy. A new key cannot exceed the ceiling.
HTTP 401Check the Bearer header and the key's expiry and revocation status under My keys.
Reads work but edits or deletions return HTTP 403Check the organization ceiling, the key or OAuth grant level, and access to the target resource.
HTTP 403 credential_type_not_allowedYou 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:

AreaEndpoints
Codesqrcodes/list, qrcodes/getContent, qrcodes/getOperation
Batch templates and sub-codestemplates/list, templates/get, templates/listQrcodes, templates/getSubcode
Forms and recordsrecord/getFormList, forms/getTemplate, record/getRecord, record/getRecords, record/searchRecords, record/addRecord, certificates/verify
Metrics and organizationmetrics/list, metrics/get, metrics/query, projects/list
Credential and quotaauth/getContext, usage/get
v1 APIsEvery /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_Abc123456

Code examples ​

bash
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}'
python
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)
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 <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
<?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:

CapabilityAuthenticationWhere to get it
V2 APIPersonal API key or OAuth; some existing endpoints also accept a legacy organization keyThis page
v1 APIs (no longer updated)Organization keyData Management → Data API in the console
QR code image toolsNone—
Label Generation · public stylesNo key; pass the public style IDLabel design library
Label Generation · private stylesapi_key and sign signature in request parameters"API对接" (API Integration) on the label style's detail page
CaoLiao Scanner skill packageLogin by scan, or a Scanner API KeyThe CaoLiao Scanner WeChat Mini Program
Admin MCPOAuth authorization, no keyAuthorize when the client connects
Scan-side MCP, A2ANone—