跳转到主要内容
NekoHub 支持两种鉴权方式：
  • JWT 登录：供浏览器管理后台和代表具体用户执行的 API 调用使用
  • API key：供脚本、自动化、CI/CD 和 MCP 使用

​
JWT 登录

管理后台通过用户名密码登录。后端返回短期有效的 access token 和长期有效的 refresh token。

​
登录

curl -X POST http://localhost:5121/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'
真实响应带有 data 包装： 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g...",
    "accessTokenExpiresAtUtc": "2026-04-08T12:15:00Z",
    "refreshTokenExpiresAtUtc": "2026-05-08T12:00:00Z",
    "user": {
      "id": "01956f8d-0000-0000-0000-000000000001",
      "username": "admin",
      "role": "superAdmin",
      "isActive": true,
      "permissions": []
    }
  }
}

​
使用 access token

后续请求通过 Authorization 头发送： 
curl http://localhost:5121/api/v1/assets \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

​
刷新 access token

默认情况下 access token 有效期为 15 分钟。刷新时无需重新输入用户名密码： 
curl -X POST http://localhost:5121/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."}'
刷新接口同样返回新的 data.accessToken、data.refreshToken、过期时间和用户信息。

​
Token 有效期

Token默认时长环境变量
Access token15 分钟Auth__Jwt__AccessTokenMinutes
Refresh token30 天Auth__Jwt__RefreshTokenDays
这些值由后端签发和校验；前端只负责持有 token 并在必要时调用刷新接口。

​
API key

API key 主要面向非交互式客户端：脚本、CI/CD、自动化流水线和 /mcp 端点。
API key 通过环境变量配置，不在后台里生成。新增或轮换 key 需要修改部署环境并重启服务。
API key 是长期凭据，请把它当作密钥处理，不要提交到仓库，也不要直接写进公开客户端。

​
启用 API key

Auth__ApiKey__Enabled=true
Auth__ApiKey__Keys__0=your-strong-random-api-key
如需多个 key，可继续追加 Auth__ApiKey__Keys__1、Auth__ApiKey__Keys__2。

​
使用 API key

NekoHub 的 API key 使用 Authorization: Bearer <API_KEY>，不要使用旧的自定义 Header 写法： 
curl http://localhost:5121/api/v1/assets \
  -H "Authorization: Bearer your-strong-random-api-key"
/mcp 端点同样如此： 
curl http://localhost:5121/mcp \
  -H "Authorization: Bearer your-strong-random-api-key"

​
如何选择

场景推荐方式
浏览器管理后台JWT 登录
代表具体用户的 API 调用JWT 登录
脚本和自动化API key
MCP 集成API key（必需）
CI/CDAPI key