密钥管理

密钥管理

codingas.com 的”密钥”指签发给调用方的网关 API Key（sk- 开头），用于调用 /v1/* 端点。它与上游 Provider Key（OpenAI/Anthropic 的密钥，见 Provider 管理）不同。

管理 API

所有管理 API 需会话认证（Authorization: Bearer <token>，token 通过 登录 获取）。

操作	方法	端点
创建 Key	POST	/api/v1/user-api-keys
查询全部（管理员）	GET	/api/v1/user-api-keys
按用户查询	GET	/api/v1/user-api-keys?userId={id}
查询我的 Key	GET	/api/v1/me/api-keys
查询详情	GET	/api/v1/user-api-keys/{id}
Key 详情（元信息）	GET	/api/v1/user-api-keys/{id}/detail
更新	PUT	/api/v1/user-api-keys/{id}
删除	DELETE	/api/v1/user-api-keys/{id}

创建 Key

curl -X POST http://localhost:8080/api/v1/user-api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "applicationId": 1,
    "name": "my-app-key"
  }'

响应（明文仅此一次返回，请妥善保存）：

{
  "id": 1,
  "keyPrefix": "sk-****",
  "apiKeyPlain": "sk-xxxxxxxx-my-app-key"
}

请求字段：

字段	类型	必填	说明
userId	Long	是	Key 归属用户 ID（可通过 GET /api/v1/auth/me 获取）
applicationId	Long	是	授权访问的应用 ID（权限锚点，决定可访问的渠道与模型范围）
name	String	是	密钥名称（便于识别）

查询 Key

# 管理员查询全部
curl http://localhost:8080/api/v1/user-api-keys \
  -H "Authorization: Bearer $TOKEN"

# 当前登录用户的 Key
curl http://localhost:8080/api/v1/me/api-keys \
  -H "Authorization: Bearer $TOKEN"

列表接口仅返回 keyPrefix 等元信息，不返回明文。明文丢失后只能重新创建。

删除 Key

curl -X DELETE http://localhost:8080/api/v1/user-api-keys/1 \
  -H "Authorization: Bearer $TOKEN"

删除后 Key 立即失效，无法再用于调用网关。

访问控制

调用方 API Key 的访问控制通过以下机制实现：

机制	说明
应用渠道授权	Key 关联应用，应用决定可见渠道与模型（应用管理）
Token 限额	用户级 Token 配额（Token 计量与配额）
存储安全	网关仅存 Key 前缀（keyPrefix）与 SHA-256 哈希，认证时哈希比对、不解密明文

字段演进

API Key 级的 models（模型白名单）与 quota（额度）字段已移除（Flyway V49），模型可见性改由应用渠道授权控制，额度改由 TokenLimit 控制。

功能清单

功能	状态
API Key CRUD	✅
应用渠道授权（模型可见性）	✅
Token 限额（用户级）	规则管理 ✅（运行时扣减尚未接入请求链路）