认证方式

OpenAPI 使用基于 JWT Token 的认证机制，所有请求需在 HTTP Header 中携带有效的 Token。

---

Token 获取

方式一：用户登录获取

通过 Admin API 的登录接口获取用户级 Token。

POST /snail-ai/user/login

请求体：

字段	类型	必填	说明
username	string	是	用户名
password	string	是	密码

curl 示例：

curl -X POST 'http://localhost:8080/snail-ai/user/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "admin",
    "password": "your-password"
  }'

响应示例：

{
  "code": 1,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyb2xlIjoxLCJleHAiOjE3MTcyODYwMDB9.xxxxx",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoicmVmcmVzaCIsInVzZXJJZCI6MX0.xxxxx",
    "email": "admin@example.com"
  }
}

方式二：应用 Token

在管理后台创建应用（App）时，系统会自动生成一个应用级 Token。该 Token 可直接用于 OpenAPI 调用，无需登录流程，适合服务端集成场景。

应用 Token 可在管理后台的 应用管理 页面查看。

---

请求认证

在每次 API 请求的 HTTP Header 中添加 Snail-Ai-Auth 字段：

Snail-Ai-Auth: <your-token>

示例：

curl -X POST 'http://localhost:8080/snail-ai/open-api/chat' \
  -H 'Content-Type: application/json' \
  -H 'Snail-Ai-Auth: eyJhbGciOiJIUzI1NiJ9...' \
  -d '{"agentId": 1, "openId": "user-001", "content": "你好"}'

---

Token 刷新

用户级 Token 有过期时间，过期前可使用 Refresh Token 获取新的访问 Token。

POST /snail-ai/auth/refreshToken

请求体：

字段	类型	必填	说明
refreshToken	string	是	刷新令牌

curl 示例：

curl -X POST 'http://localhost:8080/snail-ai/auth/refreshToken' \
  -H 'Content-Type: application/json' \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiJ9..."}'

响应示例：

{
  "code": 1,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...(新 token)",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...(新 refreshToken)"
  }
}

---

认证错误

当 Token 无效、过期或缺失时，API 返回以下错误：

Token 缺失：

{
  "code": 401,
  "msg": "请提供认证 Token",
  "data": null
}

Token 过期：

{
  "code": 401,
  "msg": "Token 已过期，请重新登录或刷新 Token",
  "data": null
}

Token 无效：

{
  "code": 401,
  "msg": "无效的 Token",
  "data": null
}

---

请求频率限制

为保障服务稳定性，OpenAPI 对请求频率进行限制：

限制维度	限制值	说明
单 Token	60 次/分钟	超出后返回 429 错误
对话接口	10 次/分钟	流式对话接口的独立限制
知识库查询	30 次/分钟	搜索和问答接口的独立限制

超频响应示例：

{
  "code": 429,
  "msg": "请求频率超出限制，请稍后重试",
  "data": null
}

---

最佳实践

1. 安全存储 Token：不要将 Token 硬编码在前端代码中，建议通过环境变量或密钥管理服务存储
2. 及时刷新：在 Token 即将过期时提前刷新，避免中断服务
3. 使用应用 Token：服务端集成场景优先使用应用 Token，无需处理登录和刷新逻辑
4. 错误重试：收到 401 错误时自动尝试刷新 Token，收到 429 错误时实现退避重试