认证与授权
概述
智航云 AI 中台使用 API Key 进行身份认证。每个 API 请求都必须携带有效的 API Key，通过 X-API-Key 请求头或 Authorization: Bearer 请求头传递。
获取 API Key
方式一：控制台创建
登录 智航云 AI 中台，进入「设置」->「开发者」页面，点击「创建 API Key」。
方式二：API 创建
使用已有的 API Key 创建新 Key：
bash
curl -X POST https://api.invoratec.cn/v1/auth/api-keys \
-H "X-API-Key: claw_xxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Key",
"permissions": ["read", "write"]
}'python
claw = ClawPlatform(api_key="claw_xxxx")
# API Key 管理需要直接调用 REST API
import requests
resp = requests.post(
"https://api.invoratec.cn/v1/auth/api-keys",
headers={"X-API-Key": "claw_xxxx"},
json={"name": "Production Key", "permissions": ["read", "write"]}
)
print(resp.json())javascript
const resp = await fetch('https://api.invoratec.cn/v1/auth/api-keys', {
method: 'POST',
headers: {
'X-API-Key': 'claw_xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Production Key',
permissions: ['read', 'write']
})
})
const data = await resp.json()
console.log(data.key, data.secret)重要
创建时返回的 secret 仅显示一次。请妥善保存，丢失后无法恢复，只能重新创建。
使用 API Key
在每个请求中添加 X-API-Key 请求头：
bash
curl https://api.invoratec.cn/v1/tools \
-H "X-API-Key: claw_a1b2c3d4..."也支持 Authorization: Bearer 格式：
bash
curl https://api.invoratec.cn/v1/tools \
-H "Authorization: Bearer claw_a1b2c3d4..."权限模型
每个 API Key 具有一组权限，控制可访问的操作类型：
| 权限 | 说明 | 允许的操作 |
|---|---|---|
read | 只读权限 | GET 请求、查询数据、AI 对话 |
write | 读写权限 | 创建、更新、删除资源、执行工具 |
admin | 管理员权限 | API Key 管理、账户设置 |
创建 Key 时指定权限：
json
{
"name": "Read-Only Monitor",
"permissions": ["read"]
}如果 Key 权限不足，API 返回 403 Forbidden：
json
{
"error": {
"code": "FORBIDDEN",
"message": "此操作需要 write 权限"
}
}服务层级与限流
服务层级
| 层级 | 价格 | 每分钟请求 | 每日请求 | AI 对话 | 备注 |
|---|---|---|---|---|---|
| 免费 (free) | 免费 | 10 | 1,000 | 基础模型 | 开发测试用 |
| 基础 (basic) | 按量 | 100 | 10,000 | 全部模型 | 小型项目 |
| 专业 (pro) | 按量 | 500 | 100,000 | 全部模型 + 优先队列 | 生产环境 |
| 企业 (enterprise) | 定制 | 定制 | 定制 | 私有化部署 | 大型企业 |
限流机制
每个响应的 Header 中包含当前限流状态：
X-RateLimit-Limit: 100 # 每分钟上限
X-RateLimit-Remaining: 95 # 剩余次数
X-RateLimit-Reset: 1714500000 # 重置时间 (Unix timestamp)超过限制时返回 429 Too Many Requests：
json
{
"error": {
"code": "RATE_LIMITED",
"message": "请求过于频繁，请稍后重试"
}
}限流处理建议
python
import time
from invoratec.client import ClawAPIError
def call_with_retry(fn, max_retries=3):
for attempt in range(max_retries):
try:
return fn()
except ClawAPIError as e:
if e.status_code == 429:
wait = 2 ** attempt # 指数退避
time.sleep(wait)
else:
raise
raise Exception("重试次数用尽")javascript
async function callWithRetry(fn, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn()
} catch (err) {
if (err.statusCode === 429) {
const wait = Math.pow(2, attempt) * 1000
await new Promise(r => setTimeout(r, wait))
} else {
throw err
}
}
}
throw new Error('重试次数用尽')
}查看用量统计
bash
curl https://api.invoratec.cn/v1/auth/usage \
-H "X-API-Key: claw_xxxx"python
import requests
resp = requests.get(
"https://api.invoratec.cn/v1/auth/usage",
headers={"X-API-Key": "claw_xxxx"}
)
usage = resp.json()
print(f"今日: {usage['usage']['today']}/{usage['limits']['perDay']}")javascript
const resp = await fetch('https://api.invoratec.cn/v1/auth/usage', {
headers: { 'X-API-Key': 'claw_xxxx' }
})
const usage = await resp.json()
console.log(`今日: ${usage.usage.today}/${usage.limits.perDay}`)响应示例：
json
{
"tier": "basic",
"usage": { "today": 42, "month": 1200 },
"limits": { "perDay": 10000, "perMinute": 100 }
}吊销 API Key
当 Key 泄露或不再需要时，应立即吊销：
bash
curl -X DELETE https://api.invoratec.cn/v1/auth/api-keys/KEY_ID \
-H "X-API-Key: claw_xxxx"吊销后，该 Key 将被标记为 enabled: false，后续使用该 Key 的请求将返回 401 Unauthorized。
安全建议
- 不要在客户端代码中硬编码 API Key。使用环境变量或密钥管理服务。
- 使用最小权限原则。只读场景使用
read权限的 Key。 - 定期轮换 Key。建议每 90 天轮换一次生产环境的 Key。
- 监控用量。定期检查
/v1/auth/usage，异常用量可能意味着 Key 泄露。 - 使用 HTTPS。所有 API 请求必须通过 HTTPS 发送。
bash
# 推荐：使用环境变量
export CLAW_API_KEY=claw_xxxx
# 在代码中读取python
import os
claw = ClawPlatform(api_key=os.environ["CLAW_API_KEY"])javascript
const claw = new ClawPlatform({
apiKey: process.env.CLAW_API_KEY
})下一步
- 快速开始 -- 5 分钟完成第一次 API 调用
- 核心概念 -- 了解平台架构
- API 参考: 认证 -- 完整 API 端点文档