Auth

本页基于旧 docs/API_REFERENCE.md 整理认证相关接口，作为开发和联调用的高频入口。

认证方式

受保护接口通常通过以下 Header 传递认证信息：

Authorization: Bearer {access_token}

在开发态或特殊本地联调场景下，系统也可能启用禁用鉴权模式，但这不应被当成默认产品行为。

鉴权要求

路径	默认要求
/api/auth/register	公共接口
/api/auth/login	公共接口
/api/auth/refresh	公共接口
/api/auth/me	需要 Bearer Token
/api/auth/logout	需要 Bearer Token
/api/auth/change-password	需要 Bearer Token
/api/auth/logout-all	需要 Bearer Token

接口清单

公共接口

方法	路径	说明
POST	/api/auth/register	注册新用户
POST	/api/auth/login	登录并获取 token
POST	/api/auth/refresh	用 refresh token 刷新 access token

受保护接口

方法	路径	说明
GET	/api/auth/me	获取当前用户 claims
POST	/api/auth/logout	注销当前 token / refresh token
POST	/api/auth/change-password	修改当前用户密码
POST	/api/auth/logout-all	注销当前用户所有会话

常见请求体

注册

• username
• email
• password

登录

• username_or_email
• password

刷新 Token

• refresh_token

登出

当前实现优先从 Authorization: Bearer {access_token} 读取当前 access token 做立即失效；如果请求体里提供了 refresh_token，也会作为兼容兜底路径使用。

常见返回

登录 / 刷新成功

前端通常会拿到：

• access_token
• refresh_token
• token_type
• expires_in
• user

受保护接口成功

/api/auth/me 返回当前 UserClaims；logout、change-password、logout-all 当前更偏命令式接口，成功时可能只返回 204 No Content。

常见错误

状态码	场景
400	请求体校验失败
401	token 缺失、无效或已过期
409	注册时用户已存在
429	登录 / 注册 / refresh 命中认证限流

联调建议

• 先用 POST /api/auth/login 取 token，再联调受保护接口。
• 如果你在本地用了 --disable-auth，也不要默认生产环境会允许匿名访问。
• 改 token 结构或 claims 字段时，要同步检查前端登录态模型和请求拦截器。

前端最关心的返回字段

认证链路里前端最常依赖：

• access_token
• refresh_token
• token_type
• expires_in
• user

其中 user 通常至少包含：

• id
• username
• email
• role

开发注意点

• 不要把“开发时关闭鉴权”误当成真实部署默认行为。
• 新增受保护接口时，要同时考虑中间件校验和 handler 级兜底。
• 如果修改了 token 或 user 返回结构，要同步更新前端鉴权状态模型。

相关页面

• API 总览
• 后端开发
• 后端审计