UGUG Auth

API 文档

UG 鉴权中心 v0.2.0 · 标准 REST API · 完整 OIDC Provider

Base URL: https://auth.ug666.topJWT RS256

公开 API

无需认证，所有客户端可直接调用。Base URL：https://auth.ug666.top

POST/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": "注册成功，请查收验证邮件"
  }
}
POST/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"
    }
  }
}
POST/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"
    }
  }
}
POST/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
  }
}
POST/api/auth/logout

单设备登出，清除当前 Refresh Token。

请求示例 (curl)

curl -X POST https://auth.ug666.top/api/auth/logout \
  -H "Authorization: Bearer <accessToken>"

响应示例

{
  "success": true,
  "message": "已登出"
}
POST/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": "已在所有设备登出"
}
POST/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": "重置密码邮件已发送（如账号存在）"
}
POST/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 客户端库。

GET/api/oidc/authorize

授权端点，发起 Authorization Code Flow（支持 PKCE）。

请求示例 (curl)

# 通常由浏览器重定向，以下为参数示意
GET /api/oidc/authorize
  ?response_type=code
  &client_id=your_app_id
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
  &scope=openid%20profile%20email
  &state=random_state
  &code_challenge=S256_challenge
  &code_challenge_method=S256

响应示例

# 重定向到 redirect_uri，携带 code 参数
HTTP/1.1 302 Found
Location: https://yourapp.com/callback
  ?code=authorization_code
  &state=random_state
POST/api/oidc/token

Token 端点，使用授权码换取 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"
}
GET/api/oidc/userinfo

UserInfo 端点，使用 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"
}
POST/api/oidc/introspect

Token 自省端点，验证 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
}
POST/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 规范）
GET/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>

GET/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"
  }
}
PATCH/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"
  }
}
POST/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": "密码修改成功"
}
GET/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"
    }
  ]
}
DELETE/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": "设备已移除"
}

Well-known

OIDC Discovery 和 JWKS 端点，无需认证，公开可访问。

GET/.well-known/openid-configuration

OIDC 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"]
}
GET/.well-known/jwks.json

RSA 公钥 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"
    }
  ]
}