OAuth Third-Party Login Module
Feature Description
The API prefix is https://88api.ai
Supports third-party account login via GitHub, OIDC, LinuxDO, WeChat, Telegram, and more, as well as account binding and automatic registration. The login flow is completed through browser redirection.
🔐 No Authentication Required
GitHub OAuth Redirection
- Interface Name:GitHub OAuth Redirection
- HTTP Method:GET
- Path:
/api/oauth/github - Authentication Requirement:Public
- Function Description:Handles GitHub OAuth callback to complete user login or account binding
💡 Request Example:
_// 前端通过重定向方式调用,通常由GitHub OAuth授权后自动回调 _window.location.href = `https://github.com/login/oauth/authorize?client_id=${github_client_id}&state=${state}&scope=user:email`;✅ Successful Response Example:
{
"success": true,
"message": "登录成功",
"data": {
"token": "user_access_token",
"user": {
"id": 1,
"username": "github_user",
"display_name": "GitHub User",
"email": "user@example.com"
}
}
}❗ Failure Response Example:
{
"success": false,
"message": "管理员未开启通过 GitHub 登录以及注册"
}🧾 Field Description:
code(String): GitHub OAuth authorization code, provided by GitHub upon callbackstate(String): Anti-CSRF state code, must match the one stored in the session
OIDC General OAuth Redirection
- Interface Name:OIDC General OAuth Redirection
- HTTP Method:GET
- Path:
/api/oauth/oidc - Authentication Requirement:Public
- Function Description:Handles OIDC OAuth callback, supports general OpenID Connect protocol login
💡 Request Example:
_// 前端通过重定向方式调用 _
const url = new URL(auth_url);
url.searchParams.set('client_id', client_id);
url.searchParams.set('redirect_uri', `${window.location.origin}/oauth/oidc`);
url.searchParams.set('response_type', 'code');
url.searchParams.set('scope', 'openid profile email');
url.searchParams.set('state', state);
window.location.href = url.toString();✅ Successful Response Example:
{
"success": true,
"message": "登录成功",
"data": {
"token": "user_access_token",
"user": {
"id": 1,
"username": "oidc_user",
"email": "user@example.com"
}
}
}❗ Failure Response Example:
{
"success": false,
"message": "OIDC 获取用户信息失败!请检查设置!"
}🧾 Field Description:
code(String): OIDC authorization codestate(String): Anti-CSRF state code
LinuxDo OAuth Redirection
- Interface Name:LinuxDo OAuth Redirection
- HTTP Method:GET
- Path:
/api/oauth/linuxdo - Authentication Requirement:Public
- Function Description:Handles LinuxDo OAuth callback, supports login via LinuxDo community account
💡 Request Example:
_// 前端通过重定向方式调用 _
window.location.href = `https://connect.linux.do/oauth2/authorize?response_type=code&client_id=${linuxdo_client_id}&state=${state}`;✅ Successful Response Example:
{
"success": true,
"message": "登录成功",
"data": {
"token": "user_access_token",
"user": {
"id": 1,
"username": "linuxdo_user",
"display_name": "LinuxDo User"
}
}
}❗ Failure Response Example:
{
"success": false,
"message": "管理员关闭了新用户注册"
}🧾 Field Description:
code(String): LinuxDo OAuth authorization codestate(String): Anti-CSRF state codeerror(String): Optional, OAuth error codeerror_description(String): Optional, error description
WeChat QR Code Login Redirection
- Interface Name:WeChat QR Code Login Redirection
- HTTP Method:GET
- Path:
/api/oauth/wechat - Authentication Requirement:Public
- Function Description:Handles WeChat QR code login, completes the login process via verification code
💡 Request Example:
const response = await fetch(`/api/oauth/wechat?code=${wechat_verification_code}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "登录成功",
"data": {
"token": "user_access_token",
"user": {
"id": 1,
"username": "wechat_user",
"wechat_id": "wechat_openid"
}
}
}❗ Failure Response Example:
{
"success": false,
"message": "验证码无效或已过期"
}🧾 Field Description:
code (String): Verification code obtained from WeChat QR scan
WeChat Account Binding
- Interface Name:WeChat Account Binding
- HTTP Method:GET
- Path:
/api/oauth/wechat/bind - Authentication Requirement:Public
- Function Description:Binds the WeChat account to an existing user account
💡 Request Example:
const response = await fetch(`/api/oauth/wechat/bind?code=${wechat_verification_code}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "微信账户绑定成功!"
}❗ Failure Response Example:
{
"success": false,
"message": "验证码无效或该微信账户已被绑定"
}🧾 Field Description:
code (String): Verification code obtained from WeChat QR scan
Email Binding
- Interface Name:Email Binding
- HTTP Method:GET
- Path:
/api/oauth/email/bind - Authentication Requirement:Public
- Function Description:Binds an email address to the user account via email verification code
💡 Request Example:
const response = await fetch(`/api/oauth/email/bind?email=${email}&code=${email_verification_code}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "邮箱账户绑定成功!"
}❗ Failure Response Example:
{
"success": false,
"message": "验证码无效或邮箱已被使用"
}🧾 Field Description:
email(String): Email address to be boundcode(String): Email verification code
Telegram Login
- Interface Name:Telegram Login
- HTTP Method:GET
- Path:
/api/oauth/telegram/login - Authentication Requirement:Public
- Function Description:Completes user login via Telegram Widget
💡 Request Example:
const params = {
id: telegram_user_id,
first_name: "John",
last_name: "Doe",
username: "johndoe",
photo_url: "https://...",
auth_date: 1640995200,
hash: "telegram_hash"
};
const query = new URLSearchParams(params).toString();
const response = await fetch(`/api/oauth/telegram/login?${query}`, {
method: 'GET'
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "登录成功",
"data": {
"token": "user_access_token",
"user": {
"id": 1,
"username": "telegram_user",
"telegram_id": "123456789"
}
}
}❗ Failure Response Example:
{
"success": false,
"message": "Telegram验证失败"
}🧾 Field Description:
id(String): Telegram User IDfirst_name(String): User first namelast_name(String): User last name, optionalusername(String): Telegram username, optionalphoto_url(String): Avatar URL, optionalauth_date(Number): Authentication timestamphash(String): Telegram verification hash
Telegram Account Binding
- Interface Name:Telegram Account Binding
- HTTP Method:GET
- Path:
/api/oauth/telegram/bind - Authentication Requirement:Public
- Function Description:Binds the Telegram account to an existing user account
💡 Request Example:
// 通过TelegramLoginButton组件自动处理参数
// 参数格式与Telegram登录相同
const response = await fetch('/api/oauth/telegram/bind', {
method: 'GET',
params: telegram_auth_params
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "Telegram账户绑定成功!"
}❗ Failure Response Example:
{
"success": false,
"message": "该Telegram账户已被绑定"
}🧾 Field Description:
Parameter format is the same as the Telegram login interface
Get Random State (Anti-CSRF)
- Interface Name:Get Random State
- HTTP Method:GET
- Path:
/api/oauth/state - Authentication Requirement:Public
- Function Description:Generates a random state parameter for CSRF protection in the OAuth flow
💡 Request Example:
let path = '/api/oauth/state';
let affCode = localStorage.getItem('aff');
if (affCode && affCode.length > 0) {
path += `?aff=${affCode}`;
}
const response = await fetch(path, {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
});
const data = await response.json();✅ Successful Response Example:
{
"success": true,
"message": "",
"data": "random_state_string_12chars"
}❗ Failure Response Example:
{
"success": false,
"message": "生成state失败"
}🧾 Field Description:
aff(String): Optional, referral code parameter, used to record user sourcedata(String): The returned random state string, 12 characters long