API 文档
UG 鉴权中心 v0.2.0 · 标准 REST API · 完整 OIDC Provider
公开 API
无需认证,所有客户端可直接调用。Base URL:https://auth.ug666.top
/api/auth/register注册新用户,注册成功后发送验证邮件。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "YourStr0ngP@ss",
"username": "alice"
}'响应示例
{
"success": true,
"data": {
"userId": "clxxxxxxxxxxxxx",
"message": "注册成功,请查收验证邮件"
}
}/api/auth/verify-email验证邮箱,验证成功后返回 Access Token。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/verify-email \
-H "Content-Type: application/json" \
-d '{
"userId": "clxxxxxxxxxxxxx",
"code": "123456"
}'响应示例
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900,
"user": {
"id": "clxxx",
"email": "user@example.com",
"username": "alice"
}
}
}/api/auth/login用户登录,返回 Access Token,同时设置 HttpOnly Cookie 存储 Refresh Token。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "YourStr0ngP@ss",
"appId": "your_app_id"
}'响应示例
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900,
"user": {
"id": "clxxx",
"email": "user@example.com",
"username": "alice"
}
}
}/api/auth/refresh刷新 Access Token,使用 Refresh Token Rotation,每次刷新都会换发新 RT。
refresh_token 通过 HttpOnly Cookie (rt) 自动传递,无需手动添加请求体。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/refresh \ --cookie "rt=your_refresh_token"
响应示例
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 900
}
}/api/auth/logout单设备登出,清除当前 Refresh Token。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/logout \ -H "Authorization: Bearer <accessToken>"
响应示例
{
"success": true,
"message": "已登出"
}/api/auth/logout-all全设备登出,撤销该用户的所有 Refresh Token。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/logout-all \ -H "Authorization: Bearer <accessToken>"
响应示例
{
"success": true,
"message": "已在所有设备登出"
}/api/auth/forgot-password发送密码重置邮件,无论邮箱是否存在均返回相同响应(防枚举)。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{ "email": "user@example.com" }'响应示例
{
"success": true,
"message": "重置密码邮件已发送(如账号存在)"
}/api/auth/reset-password使用邮件中的 token 重置密码,token 一次性有效。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/auth/reset-password \
-H "Content-Type: application/json" \
-d '{
"token": "reset_token_from_email",
"newPassword": "NewStr0ngP@ss"
}'响应示例
{
"success": true,
"message": "密码重置成功"
}OIDC
标准 OpenID Connect 端点,兼容所有 OIDC 客户端库。
/api/oidc/tokenToken 端点,使用授权码换取 Access Token / Refresh Token。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/oidc/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=authorization_code" \ -d "redirect_uri=https://yourapp.com/callback" \ -d "client_id=your_app_id" \ -d "code_verifier=pkce_verifier"
响应示例
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 900,
"refresh_token": "rt_xxxxxxxxxxxxxxxx",
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"scope": "openid profile email"
}/api/oidc/userinfoUserInfo 端点,使用 Access Token 获取用户信息。
请求示例 (curl)
curl https://auth.ug666.top/api/oidc/userinfo \ -H "Authorization: Bearer <access_token>"
响应示例
{
"sub": "clxxxxxxxxxxxxx",
"email": "user@example.com",
"email_verified": true,
"name": "alice",
"preferred_username": "alice"
}/api/oidc/introspectToken 自省端点,验证 token 是否有效(需要应用凭证)。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/oidc/introspect \ -H "Content-Type: application/x-www-form-urlencoded" \ -u "your_app_id:your_app_secret" \ -d "token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
响应示例
{
"active": true,
"sub": "clxxxxxxxxxxxxx",
"scope": "openid profile email",
"client_id": "your_app_id",
"exp": 1714000000
}/api/oidc/revoke撤销 Token(access_token 或 refresh_token)。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/oidc/revoke \ -H "Content-Type: application/x-www-form-urlencoded" \ -u "your_app_id:your_app_secret" \ -d "token=rt_xxxxxxxxxxxxxxxx" \ -d "token_type_hint=refresh_token"
响应示例
HTTP/1.1 200 OK # 空响应体(RFC 7009 规范)
/api/oidc/end-session单点登出端点,清除服务端 session 并重定向。
请求示例 (curl)
GET /api/oidc/end-session ?id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... &post_logout_redirect_uri=https%3A%2F%2Fyourapp.com &state=random_state
响应示例
# 重定向到 post_logout_redirect_uri HTTP/1.1 302 Found Location: https://yourapp.com?state=random_state
用户
需要 Authorization: Bearer <access_token>
/api/user/profile查看当前用户个人信息。
请求示例 (curl)
curl https://auth.ug666.top/api/user/profile \ -H "Authorization: Bearer <access_token>"
响应示例
{
"success": true,
"data": {
"id": "clxxxxxxxxxxxxx",
"email": "user@example.com",
"username": "alice",
"avatarUrl": "https://cdn.example.com/avatar.jpg"
}
}/api/user/profile修改个人信息(username / avatarUrl 任选其一)。
请求示例 (curl)
curl -X PATCH https://auth.ug666.top/api/user/profile \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"username": "alice_new",
"avatarUrl": "https://cdn.example.com/new-avatar.jpg"
}'响应示例
{
"success": true,
"data": {
"id": "clxxxxxxxxxxxxx",
"email": "user@example.com",
"username": "alice_new",
"avatarUrl": "https://cdn.example.com/new-avatar.jpg"
}
}/api/user/change-password修改密码,需提供当前密码作为二次验证。
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/user/change-password \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"currentPassword": "OldStr0ngP@ss",
"newPassword": "NewStr0ngP@ss"
}'响应示例
{
"success": true,
"message": "密码修改成功"
}/api/user/devices查看当前用户已登录的设备列表。
请求示例 (curl)
curl https://auth.ug666.top/api/user/devices \ -H "Authorization: Bearer <access_token>"
响应示例
{
"success": true,
"data": [
{
"id": "device_id_1",
"deviceName": "Chrome on macOS",
"ipAddress": "1.2.3.4",
"lastActiveAt": "2026-04-12T08:00:00.000Z"
}
]
}/api/user/devices/:deviceId移除指定设备的登录会话,强制该设备下线。
请求示例 (curl)
curl -X DELETE https://auth.ug666.top/api/user/devices/device_id_1 \ -H "Authorization: Bearer <access_token>"
响应示例
{
"success": true,
"message": "设备已移除"
}接入方式
不提供 SDK,也不需要在接入方复制我们的代码。业务后端二选一:调验签接口(最简单),或本地验签(少一次网络往返)。前端只用任意标准 OIDC 库。
/api/apps/verify-token校验 access token 并返回用户与角色
用应用凭据(X-App-Id / X-App-Secret)调用;token 的 aud 必须等于该应用,返回 valid=false 表示无效、已撤销或用户已被封禁
请求示例 (curl)
curl -X POST https://auth.ug666.top/api/apps/verify-token \
-H 'content-type: application/json' \
-H 'x-app-id: your_app_id' \
-H 'x-app-secret: <app_secret>' \
-d '{"accessToken":"<access_token>"}'响应示例
{
"success": true,
"data": {
"valid": true,
"user": { "id": "u_xxx", "email": "a@b.com", "roles": ["admin"], "tokenVersion": 3 }
}
}本地验签要校验什么
- 公钥从
/.well-known/jwks.json取(按kid匹配),缓存但允许轮换 - 算法固定
RS256,不要接受none或对称算法 iss= https://auth.ug666.top,aud= 你的 appIdexp/nbf必须校验,容忍时钟偏移不超过 60 秒aud必须等于自己的 appId;不做本地校验时改为调验签接口(能感知撤销名单与封禁)
前端登录
用标准授权码 + PKCE 流程,任意 OIDC 客户端库都能接:authority 填 https://auth.ug666.top,client_id 填你的 appId,回调地址在应用的允许列表里配置。 不要在前端保存 client secret。
管理后台 API
供 UG Console 等管理端调用,全部位于 /api/v1/admin 下,使用平台管理员 Cookie 会话鉴权。未登录返回 401,越权返回 403。以下条目由路由文件生成,与实际实现一致。
应用与密钥
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/apps | 分页列表 |
| POST | /api/v1/admin/apps | 新建 |
| DELETE | /api/v1/admin/apps/:appId | 删除 |
| GET | /api/v1/admin/apps/:appId | 读取单条记录 |
| PATCH | /api/v1/admin/apps/:appId | 更新 |
| GET | /api/v1/admin/apps/:appId/admins | 读取单条记录 |
| POST | /api/v1/admin/apps/:appId/admins | 新建 |
| DELETE | /api/v1/admin/apps/:appId/admins/:userId | 删除 |
| PATCH | /api/v1/admin/apps/:appId/admins/:userId | 更新 |
| GET | /api/v1/admin/apps/:appId/members | 读取单条记录 |
| POST | /api/v1/admin/apps/:appId/members | 新建 |
| PATCH | /api/v1/admin/apps/:appId/members/:userId | 更新 |
| GET | /api/v1/admin/apps/:appId/permissions | 读取单条记录 |
| POST | /api/v1/admin/apps/:appId/permissions | 新建 |
| DELETE | /api/v1/admin/apps/:appId/permissions/:key | 删除 |
| PATCH | /api/v1/admin/apps/:appId/permissions/:key | 更新 |
| POST | /api/v1/admin/apps/:appId/regen-secret | 重置应用密钥 |
| DELETE | /api/v1/admin/apps/:appId/roles | 调整角色 |
| GET | /api/v1/admin/apps/:appId/roles | 读取角色 |
| POST | /api/v1/admin/apps/:appId/roles | 调整角色 |
| GET | /api/v1/admin/apps/:appId/roles/:roleName/permissions | 读取单条记录 |
| GET | /api/v1/admin/apps/:appId/secret | 读取应用密钥 |
审计日志
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/audit-logs | 分页列表 |
| GET | /api/v1/admin/audit-logs/export | 导出 CSV |
管理员会话
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/admin/auth/login | 管理员登录 |
| POST | /api/v1/admin/auth/logout | 管理员登出 |
| GET | /api/v1/admin/auth/me | 当前管理员 |
账号清理
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/admin/cleanup-unverified | 新建 |
gateway
| 方法 | 路径 | 说明 |
|---|---|---|
| DELETE | /api/v1/admin/gateway/:service/:...path | 删除 |
| GET | /api/v1/admin/gateway/:service/:...path | 读取单条记录 |
| PATCH | /api/v1/admin/gateway/:service/:...path | 更新 |
| POST | /api/v1/admin/gateway/:service/:...path | 新建 |
邀请
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/invites | 分页列表 |
| POST | /api/v1/admin/invites | 新建 |
| DELETE | /api/v1/admin/invites/:id | 删除 |
| PATCH | /api/v1/admin/invites/:id | 更新 |
登录历史
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/login-history | 分页列表 |
| GET | /api/v1/admin/login-history/export | 导出 CSV |
平台管理员
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/platform-admins | 分页列表 |
| POST | /api/v1/admin/platform-admins | 新建 |
| DELETE | /api/v1/admin/platform-admins/:id | 删除 |
| PATCH | /api/v1/admin/platform-admins/:id | 更新 |
会话
| 方法 | 路径 | 说明 |
|---|---|---|
| DELETE | /api/v1/admin/sessions | 删除 |
| GET | /api/v1/admin/sessions | 分页列表 |
| DELETE | /api/v1/admin/sessions/:sessionId | 删除 |
服务设置
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/settings | 分页列表 |
| PATCH | /api/v1/admin/settings | 更新 |
| POST | /api/v1/admin/settings/test-email | 发送测试邮件 |
平台用户
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/admin/users | 分页列表 |
| GET | /api/v1/admin/users/:userId | 读取单条记录 |
| POST | /api/v1/admin/users/:userId/ban | 封禁用户 |
| GET | /api/v1/admin/users/:userId/devices | 设备列表 |
| POST | /api/v1/admin/users/:userId/force-logout | 强制下线 |
| POST | /api/v1/admin/users/:userId/reset-password | 重置密码 |
| DELETE | /api/v1/admin/users/:userId/roles | 调整角色 |
| GET | /api/v1/admin/users/:userId/roles | 读取角色 |
| POST | /api/v1/admin/users/:userId/roles | 调整角色 |
| POST | /api/v1/admin/users/:userId/unban | 解封用户 |
| POST | /api/v1/admin/users/create | 新建 |
Well-known
OIDC Discovery 和 JWKS 端点,无需认证,公开可访问。
/.well-known/openid-configurationOIDC Discovery 文档,包含所有端点 URL 及支持的 scopes / grant types。
请求示例 (curl)
curl https://auth.ug666.top/.well-known/openid-configuration
响应示例
{
"issuer": "https://auth.ug666.top",
"authorization_endpoint": "https://auth.ug666.top/api/oidc/authorize",
"token_endpoint": "https://auth.ug666.top/api/oidc/token",
"userinfo_endpoint": "https://auth.ug666.top/api/oidc/userinfo",
"jwks_uri": "https://auth.ug666.top/.well-known/jwks.json",
"scopes_supported": ["openid", "profile", "email"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"id_token_signing_alg_values_supported": ["RS256"]
}/.well-known/jwks.jsonRSA 公钥 JWKS 端点,供第三方服务独立验签 JWT,无需回调。
请求示例 (curl)
curl https://auth.ug666.top/.well-known/jwks.json
响应示例
{
"keys": [
{
"kty": "RSA",
"kid": "key-id-1",
"use": "sig",
"alg": "RS256",
"n": "0vx7agoebGcQSuuPiLJXZptN9...",
"e": "AQAB"
}
]
}