88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
API Module Guide

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 callback
  • state (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 code
  • state (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 code
  • state (String): Anti-CSRF state code
  • error (String): Optional, OAuth error code
  • error_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 bound
  • code (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 ID
  • first_name (String): User first name
  • last_name (String): User last name, optional
  • username (String): Telegram username, optional
  • photo_url (String): Avatar URL, optional
  • auth_date (Number): Authentication timestamp
  • hash (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 source
  • data (String): The returned random state string, 12 characters long