API 接口文档

5 months ago

7546666

API 接口文档

本文档列出 MLiev IAM 的所有 API 接口。

公共端点（无需认证）

健康检查

方法	路径	说明
GET	`/health`	完整健康检查（含数据库、Redis 状态）
GET	`/health/simple`	简单健康检查（仅状态和时间戳）

安装向导

方法	路径	说明
GET	`/api/install/check`	检查安装状态
POST	`/api/install/test-connection`	测试数据库连接
POST	`/api/install/test-redis`	测试 Redis 连接
POST	`/api/install/submit`	提交安装配置

验证码

方法	路径	说明
POST	`/api/captcha/params`	获取验证码前端参数

管理员认证

方法	路径	认证	说明
POST	`/api/admin/auth/login`	无	管理员登录
POST	`/api/admin/auth/logout`	Admin	管理员退出
POST	`/api/admin/auth/refresh`	Admin	刷新令牌
GET	`/api/admin/auth/profile`	Admin	获取管理员信息

登录请求示例

curl -X POST http://localhost:8080/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

响应：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 86400
  }
}

用户管理（管理员）

所有接口需要管理员认证（Authorization: Bearer <admin_token>）。

基础操作

方法	路径	说明
POST	`/api/admin/users`	创建用户
GET	`/api/admin/users`	获取用户列表（分页）
GET	`/api/admin/users/:id`	获取用户详情
PUT	`/api/admin/users/:id`	更新用户信息
DELETE	`/api/admin/users/:id`	删除用户

状态与密码

方法	路径	说明
PUT	`/api/admin/users/:id/status`	更新用户状态
PUT	`/api/admin/users/:id/reset-password`	重置密码
POST	`/api/admin/users/batch`	批量操作
GET	`/api/admin/users/stats/active-count`	活跃用户统计

用户角色管理

方法	路径	说明
POST	`/api/admin/users/:id/roles/:roleId`	分配角色
DELETE	`/api/admin/users/:id/roles/:roleId`	移除角色
GET	`/api/admin/users/:id/roles`	获取用户角色
GET	`/api/admin/users/:id/with-roles`	获取用户及角色详情
POST	`/api/admin/users/:id/roles/batch`	批量分配角色
DELETE	`/api/admin/users/:id/roles/batch`	批量移除角色
PUT	`/api/admin/users/:id/roles/:roleId/primary`	设置主要角色
GET	`/api/admin/users/:id/permissions`	获取用户权限
GET	`/api/admin/users/:id/menu-tree`	获取用户菜单树
GET	`/api/admin/users/:id/departments`	获取用户部门

角色管理（管理员）

方法	路径	说明
POST	`/api/admin/roles`	创建角色
GET	`/api/admin/roles`	获取角色列表
GET	`/api/admin/roles/tree`	获取角色树形结构
GET	`/api/admin/roles/:id`	获取角色详情
PUT	`/api/admin/roles/:id`	更新角色
DELETE	`/api/admin/roles/:id`	删除角色
PUT	`/api/admin/roles/:id/status`	更新角色状态
POST	`/api/admin/roles/batch`	批量操作
POST	`/api/admin/roles/:id/permissions`	分配权限
GET	`/api/admin/roles/:id/permissions`	获取角色权限
GET	`/api/admin/roles/stats`	角色统计信息

权限管理（管理员）

方法	路径	说明
POST	`/api/admin/permissions`	创建权限
GET	`/api/admin/permissions`	获取权限列表
GET	`/api/admin/permissions/tree`	获取权限树形结构
GET	`/api/admin/permissions/menu-tree`	获取菜单树形结构
GET	`/api/admin/permissions/:id`	获取权限详情
PUT	`/api/admin/permissions/:id`	更新权限
DELETE	`/api/admin/permissions/:id`	删除权限
PUT	`/api/admin/permissions/:id/status`	更新权限状态
POST	`/api/admin/permissions/batch`	批量操作
GET	`/api/admin/permissions/stats`	权限统计信息

权限类型：菜单权限（menu）、按钮权限（button）、API 权限（api）、数据权限（data）。

部门管理（管理员）

方法	路径	说明
POST	`/api/admin/departments`	创建部门
GET	`/api/admin/departments`	获取部门列表
GET	`/api/admin/departments/tree`	获取部门树形结构
GET	`/api/admin/departments/roots`	获取根部门列表
GET	`/api/admin/departments/:id`	获取部门详情
PUT	`/api/admin/departments/:id`	更新部门
DELETE	`/api/admin/departments/:id`	删除部门
PUT	`/api/admin/departments/:id/status`	更新部门状态
PUT	`/api/admin/departments/:id/move`	移动部门
GET	`/api/admin/departments/:id/children`	获取子部门
GET	`/api/admin/departments/:id/descendants`	获取所有后代部门
POST	`/api/admin/departments/batch`	批量操作
GET	`/api/admin/departments/stats/active-count`	启用部门统计
POST	`/api/admin/departments/validate-hierarchy`	验证层级结构
POST	`/api/admin/departments/repair-hierarchy`	修复层级结构
GET	`/api/admin/departments/:id/users`	获取部门下的用户
GET	`/api/admin/managers/:managerId/departments`	根据负责人获取部门

应用管理（管理员）

方法	路径	说明
POST	`/api/admin/applications`	创建应用
GET	`/api/admin/applications`	获取应用列表
GET	`/api/admin/applications/:id`	获取应用详情
PUT	`/api/admin/applications/:id`	更新应用
DELETE	`/api/admin/applications/:id`	删除应用
GET	`/api/admin/applications/:id/keys`	获取应用签名密钥列表
POST	`/api/admin/applications/:id/keys/rotate`	轮转签名密钥
POST	`/api/admin/applications/:id/secret/reset`	重置客户端密钥
GET	`/api/admin/applications/:id/access-scope`	获取授权范围
PUT	`/api/admin/applications/:id/access-scope`	更新授权范围
POST	`/api/admin/applications/batch`	批量操作
GET	`/api/admin/applications/stats`	应用统计信息

社交登录提供商管理（管理员）

方法	路径	说明
POST	`/api/admin/social-providers`	创建提供商
GET	`/api/admin/social-providers`	获取提供商列表
GET	`/api/admin/social-providers/:id`	获取提供商详情
PUT	`/api/admin/social-providers/:id`	更新提供商
DELETE	`/api/admin/social-providers/:id`	删除提供商
POST	`/api/admin/social-providers/batch`	批量操作
GET	`/api/admin/social-providers/stats`	提供商统计信息

系统设置（管理员）

方法	路径	说明
GET	`/api/admin/settings`	获取所有设置
GET	`/api/admin/settings/:key`	获取单个设置
POST	`/api/admin/settings`	创建设置
PUT	`/api/admin/settings/:key`	更新设置
DELETE	`/api/admin/settings/:key`	删除设置
GET	`/api/admin/settings/register-fields/config`	获取注册字段配置
PUT	`/api/admin/settings/register-fields/config`	更新注册字段配置
GET	`/api/admin/settings/push/config`	获取推送服务配置
PUT	`/api/admin/settings/push/config`	更新推送服务配置
GET	`/api/admin/settings/captcha/bindings`	获取验证码场景绑定
PUT	`/api/admin/settings/captcha/bindings`	更新验证码场景绑定

验证码配置（管理员）

方法	路径	说明
GET	`/api/admin/captcha-configs`	获取配置列表
GET	`/api/admin/captcha-configs/providers`	获取支持的提供商
GET	`/api/admin/captcha-configs/:id`	获取单个配置
POST	`/api/admin/captcha-configs`	创建配置
PUT	`/api/admin/captcha-configs/:id`	更新配置
DELETE	`/api/admin/captcha-configs/:id`	删除配置

系统管理

方法	路径	认证	说明
GET	`/api/system/reload`	无	重新加载配置
GET	`/api/system/info`	无	获取系统信息

普通用户接口

方法	路径	认证	说明
POST	`/api/user/login`	无	用户登录验证
GET	`/api/user/profile`	User	获取当前用户信息
PUT	`/api/user/profile`	User	更新当前用户信息
PUT	`/api/user/password`	User	修改密码
GET	`/api/user/social-accounts`	User	获取已绑定社交账号
POST	`/api/auth/logout`	User	退出登录
POST	`/api/auth/refresh`	User	刷新令牌
GET	`/api/auth/codes`	User	获取权限码

社交登录

方法	路径	认证	说明
GET	`/social/providers`	无	获取可用提供商列表
GET	`/social/auth/:provider`	无	发起 OAuth 授权
GET	`/social/callback/:provider`	无	OAuth 回调处理
POST	`/social/bind-with-login`	无	社交账号绑定已有账户
POST	`/social/register-with-social`	无	社交账号注册新账户
POST	`/social/bind/:provider`	User	绑定社交账号
DELETE	`/social/unbind/:accountId`	User	解绑社交账号

OIDC 授权流程

详见 [OIDC 集成指南]。

方法	路径	说明
POST	`/api/oidc/login`	OIDC 登录
POST	`/api/oidc/register`	OIDC 注册
GET	`/api/oidc/auth-info`	获取授权信息
GET	`/api/oidc/flow-status`	获取流程状态
POST	`/api/oidc/send-verification-code`	发送验证码
POST	`/api/oidc/send-register-verification-code`	发送注册验证码
POST	`/api/oidc/complete-profile`	完善用户信息
GET	`/api/oidc/register-settings`	获取注册字段配置
POST	`/api/oidc/init-session`	初始化 OIDC 会话

OIDC 协议端点

方法	路径	说明
GET/POST	`/oidc/:client_id/authorize`	授权端点
GET/POST	`/oidc/:client_id/token`	令牌端点
GET/POST	`/oidc/:client_id/userinfo`	用户信息端点
POST	`/oidc/:client_id/introspect`	令牌内省
POST	`/oidc/:client_id/revoke`	令牌撤销
GET	`/oidc/:client_id/jwks`	JWKS 端点
GET	`/oidc/:client_id/.well-known/openid-configuration`	OIDC 发现文档

Webhook

方法	路径	说明
POST	`/webhook/oidc/consent`	OIDC 授权确认回调