API Keys API

clou_a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890
└──┬─┘└───────────────────────────┬───────────────────────────┘
 clou_ 前缀                 32 字节随机数的十六进制表示（64 位）

Authorization: Bearer clou_a1b2c3d4e5f6...

GET /api/v1/api-keys

curl -X GET "https://your-domain.com/api/v1/api-keys?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "8f14e45f-ceea-467a-9d0f-1a2b3c4d5e6f",
        "name": "Production API Key",
        "key_prefix": "clou_a1b2c3d",
        "user_id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
        "user": { "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c", "username": "alice" },
        "scopes": ["chat"],
        "rate_limit": 1000,
        "is_active": true,
        "last_used_at": "2026-09-24T14:30:00Z",
        "expires_at": "2027-02-11T00:00:00Z",
        "agents": [{ "id": "0b1c2d3e-...", "name": "Customer Support", "icon": "🤖" }],
        "workflows": [],
        "created_at": "2026-02-11T10:00:00Z",
        "updated_at": "2026-02-11T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

GET /api/v1/api-keys/{api_key_id}

POST /api/v1/api-keys

curl -X POST "https://your-domain.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "expires_at": "2027-02-11T00:00:00Z"
  }'

{
  "code": 0,
  "data": {
    "id": "8f14e45f-ceea-467a-9d0f-1a2b3c4d5e6f",
    "name": "Production API Key",
    "key": "clou_a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "key_prefix": "clou_a1b2c3d",
    "user_id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
    "scopes": ["chat"],
    "rate_limit": 1000,
    "is_active": true,
    "expires_at": "2027-02-11T00:00:00Z",
    "last_used_at": null,
    "agents": [],
    "workflows": [],
    "created_at": "2026-02-11T16:00:00Z",
    "updated_at": "2026-02-11T16:00:00Z"
  },
  "msg": "API key created successfully"
}

PUT /api/v1/api-keys/{api_key_id}

DELETE /api/v1/api-keys/{api_key_id}

POST /api/v1/api-keys/{api_key_id}/activate
POST /api/v1/api-keys/{api_key_id}/deactivate

GET /api/v1/api-keys/stats

{
  "code": 0,
  "data": { "total": 3, "active": 2, "inactive": 0, "expired": 1 },
  "msg": "success"
}

import os
import requests

BASE = "https://your-domain.com/api/v1"


def create_api_key(token: str, name: str, agent_ids: list[str] | None = None) -> dict:
    """创建一个绑定到指定 Agent 的 API Key。"""
    response = requests.post(
        f"{BASE}/api-keys",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json={
            "name": name,
            "expires_at": "2027-02-11T00:00:00Z",
            "agent_ids": agent_ids or [],
        },
    )
    result = response.json()
    if result["code"] != 0:
        raise RuntimeError(f"create failed: {result['code']} {result['msg']}")
    # data["key"] 只出现这一次
    print(f"created {result['data']['key_prefix']}…")
    return result["data"]


def list_api_keys(token: str, status: str = "active") -> dict:
    """按状态分页查询自己的 API Key。"""
    response = requests.get(
        f"{BASE}/api-keys",
        headers={"Authorization": f"Bearer {token}"},
        params={"page": 1, "page_size": 20, "status": status},
    )
    return response.json()["data"]


# 使用
token = os.environ["USER_TOKEN"]
new_key = create_api_key(token, "prod-chatbot")
print("把完整密钥写入密钥管理器：", new_key["key"])

const BASE = 'https://your-domain.com/api/v1';

async function createApiKey(token, name, agentIds = []) {
  const response = await fetch(`${BASE}/api-keys`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name,
      expires_at: '2027-02-11T00:00:00Z',
      agent_ids: agentIds,
    }),
  });
  const result = await response.json();
  if (result.code !== 0) {
    throw new Error(`create failed: ${result.code} ${result.msg}`);
  }
  return result.data; // data.key 只出现这一次
}

async function deactivateApiKey(token, keyId) {
  const response = await fetch(`${BASE}/api-keys/${keyId}/deactivate`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
  });
  const result = await response.json();
  if (result.code !== 0) {
    throw new Error(`deactivate failed: ${result.code} ${result.msg}`);
  }
  return result.data;
}

// 使用
const token = process.env.USER_TOKEN;
const created = await createApiKey(token, 'prod-chatbot');
console.log('完整密钥只在本次响应中可用:', created.key);