API 参考: 认证 (Auth)

认证与 API Key 管理端点。

创建 API Key

创建一个新的 API Key。

POST /v1/auth/api-keys

请求头

Header	值
X-API-Key	已有的有效 API Key
Content-Type	application/json

请求体

字段	类型	必填	说明
name	string	否	Key 名称，默认 "Default Key"
permissions	string[]	否	权限列表，默认 ["read", "write"]。可选值：read, write, admin

请求示例

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"]
  }'

响应

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "key": "claw_a1b2c3d4...",
  "secret": "clsk_x9y8z7...",
  "name": "Production Key",
  "permissions": ["read", "write"],
  "tier": "free",
  "message": "请妥善保存 secret，它只会显示一次。"
}

WARNING

secret 字段仅在创建时返回一次。密钥在数据库中以哈希形式存储，丢失后无法恢复。

状态码

状态码	说明
201	创建成功
401	API Key 无效
500	服务器错误

---

列出所有 API Key

列出当前开发者的所有 API Key。Key 值仅显示前 12 位。

GET /v1/auth/api-keys

请求头

Header	值
X-API-Key	有效的 API Key

请求示例

curl https://api.invoratec.cn/v1/auth/api-keys \
  -H "X-API-Key: claw_xxxx"

响应

{
  "keys": [
    {
      "_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "key": "claw_a1b2c3d4...",
      "name": "Production Key",
      "permissions": ["read", "write"],
      "tier": "free",
      "enabled": true,
      "createdAt": "2025-06-01T08:00:00.000Z"
    }
  ]
}

状态码

状态码	说明
200	成功
401	API Key 无效

---

吊销 API Key

将指定 Key 标记为禁用（enabled: false）。吊销后该 Key 将无法再用于认证。

DELETE /v1/auth/api-keys/{id}

路径参数

参数	类型	说明
id	string	API Key 的 _id

请求示例

curl -X DELETE https://api.invoratec.cn/v1/auth/api-keys/665f1a2b3c4d5e6f7a8b9c0d \
  -H "X-API-Key: claw_xxxx"

响应

{
  "success": true
}

状态码

状态码	说明
200	吊销成功
401	API Key 无效
500	服务器错误

---

查看 API 用量统计

获取当前开发者的 API 调用统计和限流信息。

GET /v1/auth/usage

请求头

Header	值
X-API-Key	有效的 API Key

请求示例

curl https://api.invoratec.cn/v1/auth/usage \
  -H "X-API-Key: claw_xxxx"

响应

{
  "tier": "free",
  "usage": {
    "today": 42,
    "month": 1200
  },
  "limits": {
    "perDay": 1000,
    "perMinute": 10
  }
}

响应字段

字段	类型	说明
tier	string	服务层级：free, basic, pro, enterprise
usage.today	integer	今日已用请求数
usage.month	integer	本月已用请求数
limits.perDay	integer	每日请求上限
limits.perMinute	integer	每分钟请求上限

状态码

状态码	说明
200	成功
401	API Key 无效
500	服务器错误