跳转到主要内容
NekoHub 提供两种鉴权方式，分别适用于不同的集成场景。

​
JWT Bearer

当请求代表某个登录用户执行时，应使用 JWT。 先调用 POST /api/v1/auth/login 获取 token，然后在请求头中发送： 
Authorization: Bearer <access_token>
示例： 
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:5121/api/v1/assets
JWT 只被以下端点接受：
  • POST /api/v1/auth/logout
  • GET /api/v1/auth/me

​
API key

脚本、自动化和 MCP 使用 API key。它的传递方式同样是 Bearer，不要使用旧的自定义 Header 写法： 
Authorization: Bearer <api_key>
示例： 
curl -H "Authorization: Bearer your-api-key" \
  http://localhost:5121/api/v1/assets
启用方式： 
Auth__ApiKey__Enabled=true
Auth__ApiKey__Keys__0=your-strong-random-key
/mcp 只接受 API key。

​
哪些接口接受哪种方式

接口组JWTAPI key
公开资产不需要不需要
/content/{storageKey}不需要不需要
GET /api/v1/system/ping不需要不需要
GET /api/v1/system/bootstrap不需要不需要
POST /api/v1/auth/login不需要不需要
POST /api/v1/auth/refresh不需要不需要
POST /api/v1/auth/logout需要不接受
GET /api/v1/auth/me需要不接受
/api/v1/assets接受接受
/api/v1/users接受接受
/api/v1/system/storage接受接受
/api/v1/system/ai/providers接受接受
/mcp不接受必需

​
常见鉴权错误

HTTP 状态错误码含义
401 Unauthorizedauth_unauthorized未登录或 JWT 无效
401 Unauthorizedapi_key_missingAPI key 缺失
401 Unauthorizedapi_key_invalidAPI key 无效或 Header 形式错误
401 Unauthorizedauth_token_expiredJWT 过期
403 Forbiddenauth_forbidden已认证但无权限