REST API
SwanLab 开放 API 文档，包含 OAuth2 授权与私有化后台管理接口。若您有意将 SwanLab 集成到第三方应用中，这部分内容将会对您有所帮助。
基础信息
| 接口类型 | Base URL | 适用范围 |
|---|---|---|
| OAuth2 授权 | https://api.swanlab.cn/api | 仅公有云 |
| 私有化后台管理 | https://your-swanlab-domain.com/api | 仅私有化商业版（个人版暂不支持，版本要求 APP ≥ 3.6.0） |
⚠️ 注意：
- 请求体与响应体均为
application/json - 私有化后台管理相关接口需将
your-swanlab-domain.com换成你的 SwanLab 私有化实例域名
认证
| 接口 | 认证方式 |
|---|---|
POST /auth/oauth2/token | Authorization: Basic base64(app_id:app_secret) |
GET /auth/oauth2/user/* | Authorization: Bearer <access_token> |
POST /self_hosted/root | 无需认证 |
其余 /self_hosted/* 接口 | Authorization: ApiKey <root 用户的 API Key> |
⚠️ 注意
/self_hosted/* 的请求头必须带 ApiKey 前缀（区分大小写，与 Key 之间用一个空格分隔）。只传 Key 本身会被视为未携带身份，返回 401；使用非 root 用户的 Key 则返回 403。
OAuth2 授权
面向已接入 SwanLab 的第三方应用，使用公有云地址 https://api.swanlab.cn/api：
接入咨询
OAuth2 授权仅支持公有云服务。如需接入，请联系我们：contact@swanlab.cn
- 用
app_id&app_secret换取 Access Token； - 在 Token 有效期内获取当前用户信息，或获取该用户的 API Key，用于后续调用开放接口。
| 接口 | 功能概述 | 文档链接 |
|---|---|---|
POST /auth/oauth2/token | 换取或刷新 Access Token（授权码 / refresh token） | 查看 |
GET /auth/oauth2/user/info | 用 Access Token 获取当前用户公开信息 | 查看 |
GET /auth/oauth2/user/api_key | 用 Access Token 获取该用户最新 API Key | 查看 |
私有化后台管理
面向私有化商业版实例的账号与协作管理，使用实例域名（https://your-swanlab-domain.com/api）调用。
用户管理
首次部署创建唯一的根用户（需要 License），之后支持批量建号、重置密码、停用/恢复/删除用户，以及取用任一用户的最新 API Key。
| 接口 | 功能概述 | 文档链接 |
|---|---|---|
POST /self_hosted/root | 首次部署创建唯一的根用户（需 License） | 查看 |
POST /self_hosted/users | 批量创建用户 | 查看 |
POST /self_hosted/user/password | 修改密码（根用户可修改所有用户） | 查看 |
POST /self_hosted/user/pause | 停用用户，同时清空其 API Key 与会话 | 查看 |
POST /self_hosted/user/unpause | 恢复已停用的用户 | 查看 |
POST /self_hosted/user/del | 软删除用户并清理会话与缓存 | 查看 |
GET /self_hosted/user/key/{username} | 获取用户最新 API Key，没有则自动创建 | 查看 |
组织管理
创建组织空间并指定归属人，调整成员角色。
| 接口 | 功能概述 | 文档链接 |
|---|---|---|
POST /self_hosted/team | 创建组织空间并指定归属用户 | 查看 |
POST /self_hosted/team/member | 邀请成员加入组织，或修改其角色 | 查看 |
POST /self_hosted/team/member/del | 从组织中移除成员 | 查看 |
项目协作
为项目添加协作者并设定读写权限。
| 接口 | 功能概述 | 文档链接 |
|---|---|---|
POST /self_hosted/project/collaborator | 邀请项目协作者，或修改其读写权限 | 查看 |
POST /self_hosted/project/collaborator/del | 移除项目协作者 | 查看 |
SSO 绑定
管理员可直接把已有用户与三方账号绑定，无需用户本人操作；支持解绑与换绑，停用账号或停用 Provider 下的残留绑定也能清理。
| 接口 | 功能概述 | 文档链接 |
|---|---|---|
POST /self_hosted/sso/bind | 将用户与三方账号绑定（重复绑定返回 409） | 查看 |
POST /self_hosted/sso/bind/del | 解绑三方账号，可清理停用 Provider 下的残留绑定 | 查看 |