认证方式

ModelFold 有两套彼此独立的认证体系，分别对应两类调用方：

调用方	使用位置	凭证	请求头
你的服务端程序	`/v1` 网关	API Key（`mf-` 前缀）	`Authorization: Bearer mf-...`
控制台前端	`/api/*`	登录会话令牌（JWT）	`Authorization: Bearer <token>`

调用模型只需要 API Key，不需要登录令牌。

使用 API Key 调用模型

把 Key 放在 Authorization 头里，格式固定为 Bearer <key>：

bash

curl -X POST "https://ai.modelfold.online/v1/chat/completions" \
  -H "Authorization: Bearer mf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"你好"}]}'

不要在前端代码里放 API Key

Key 等同于账号的调用权限。请只在服务端环境变量中保存，不要把 Key 写进浏览器端代码、移动端包体或公开仓库。

创建与吊销

操作	端点	说明
列出	`GET /api/keys`	返回掩码、创建时间、最后使用时间
创建	`POST /api/keys`	请求体 `{ "name": "..." }`，明文在响应里返回
吊销	`DELETE /api/keys/:id`	吊销后立即失效

约束与行为：

同一账号最多 10 个有效 Key，超出时创建接口返回 400 too_many_keys。
Key 的存储方式是哈希 + 加密：列表接口可以取回明文用于复制，但数据库中按明文检索不到任何一条记录。
吊销后该 Key 的所有请求返回 401。

认证失败的错误码

HTTP	`error.type`	触发条件
`401`	`unauthorized`	缺少 `Authorization` 头、Key 格式不对或 Key 已被吊销
`402`	`insufficient_credits`	余额不足，请求在调用上游之前就被拒绝
`429`	`rate_limited`	超过网关速率限制（默认每 Key 每分钟 60 次）

使用登录令牌调用控制台接口

/api/auth、/api/account、/api/keys、/api/wallet、/api/mail 这一组接口面向控制台，使用登录返回的 JWT：

bash

curl -X POST "https://ai.modelfold.online/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

令牌默认有效期 7 天。修改密码或重置密码后，其它设备的会话会立即失效，当前设备保留。登录设备可在控制台的「登录设备」列表中单独退出。

安全建议

为不同环境（开发 / 预发 / 生产）创建各自的 Key，便于单独吊销。
定期在控制台检查 Key 的「最后使用时间」，长期未使用的直接吊销。
网关会记录每次调用（模型、端点、状态、积分、耗时），可在控制台的调用记录里核对。

认证方式 ​

使用 API Key 调用模型 ​

创建与吊销 ​

认证失败的错误码 ​