88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
API Module Guide

Mô-đun đăng nhập bên thứ ba OAuth

Mô tả tính năng

Tiền tố API là https://88api.ai

Hỗ trợ đăng nhập bằng tài khoản bên thứ ba như GitHub, OIDC, LinuxDO, WeChat và Telegram, cùng với liên kết tài khoản và đăng ký tự động. Quy trình đăng nhập được hoàn tất thông qua chuyển hướng trình duyệt.

🔐 Không cần xác thực

Chuyển hướng GitHub OAuth

  • Tên giao diện:Chuyển hướng GitHub OAuth
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/github
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Xử lý lệnh gọi lại GitHub OAuth để hoàn tất đăng nhập người dùng hoặc liên kết tài khoản

💡 Ví dụ yêu cầu:

_// The front end is called through redirection,usually composed ofGitHub OAuthAutomatic callback after authorization  _window.location.href = `https://github.com/login/oauth/authorize?client_id=${github_client_id}&state=${state}&scope=user:email`;

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "github_user",
      "display_name": "GitHub User",
      "email": "user@example.com"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The administrator has not enabled the pass GitHub Log in and register"
}

🧾 Mô tả trường:

  • code (String): Mã ủy quyền GitHub OAuth, được GitHub cung cấp khi gọi lại
  • state (String): Mã trạng thái Anti-CSRF, phải khớp với mã được lưu trong phiên

Chuyển hướng OIDC chung OAuth

  • Tên giao diện:Chuyển hướng OIDC chung OAuth
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/oidc
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Xử lý lệnh gọi lại OIDC OAuth, hỗ trợ đăng nhập giao thức OpenID Connect chung

💡 Ví dụ yêu cầu:

_// The front end is called through redirection  _
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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "oidc_user",
      "email": "user@example.com"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "OIDC Failed to obtain user information!Please check settings!"
}

🧾 Mô tả trường:

  • code (String): mã ủy quyền OIDC
  • state (String): Mã trạng thái anti-CSRF

Chuyển hướng LinuxDo OAuth

  • Tên giao diện:Chuyển hướng LinuxDo OAuth
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/linuxdo
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Xử lý lệnh gọi lại LinuxDo OAuth, hỗ trợ đăng nhập qua tài khoản cộng đồng LinuxDo

💡 Ví dụ yêu cầu:

_// The front end is called through redirection  _
window.location.href = `https://connect.linux.do/oauth2/authorize?response_type=code&client_id=${linuxdo_client_id}&state=${state}`;

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "linuxdo_user",
      "display_name": "LinuxDo User"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The administrator has closed new user registration"
}

🧾 Mô tả trường:

  • code (String): Mã ủy quyền LinuxDo OAuth
  • state (String): Mã trạng thái anti-CSRF
  • error (String): Tùy chọn, mã lỗi OAuth
  • error_description (String): Tùy chọn, mô tả lỗi

Chuyển hướng đăng nhập mã QR WeChat

  • Tên giao diện:Chuyển hướng đăng nhập mã QR WeChat
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/wechat
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Xử lý đăng nhập bằng mã QR WeChat, hoàn tất quá trình đăng nhập thông qua mã xác minh

💡 Ví dụ yêu cầu:

const response = await fetch(`/api/oauth/wechat?code=${wechat_verification_code}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "wechat_user",
      "wechat_id": "wechat_openid"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "Verification code is invalid or expired"
}

🧾 Mô tả trường:

code (String): Mã xác minh thu được từ quá trình quét QR của WeChat

Ràng buộc tài khoản WeChat

  • Tên giao diện:Ràng buộc tài khoản WeChat
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/wechat/bind
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Liên kết tài khoản WeChat với tài khoản người dùng hiện có

💡 Ví dụ yêu cầu:

const response = await fetch(`/api/oauth/wechat/bind?code=${wechat_verification_code}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "WeChat account bound successfully!"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The verification code is invalid or the WeChat account has been bound"
}

🧾 Mô tả trường:

code (String): Mã xác minh thu được từ quá trình quét QR của WeChat

Ràng buộc email

  • Tên giao diện:Ràng buộc email
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/email/bind
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Liên kết địa chỉ email với tài khoản người dùng thông qua mã xác minh email

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Email account bound successfully!"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "The verification code is invalid or the email address has been used"
}

🧾 Mô tả trường:

  • email (String): Địa chỉ email cần ràng buộc
  • code (String): Mã xác minh email

Đăng nhập Telegram

  • Tên giao diện:Đăng nhập Telegram
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/telegram/login
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Hoàn tất đăng nhập của người dùng thông qua Widget Telegram

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "user_access_token",
    "user": {
      "id": 1,
      "username": "telegram_user",
      "telegram_id": "123456789"
    }
  }
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "TelegramAuthentication failed"
}

🧾 Mô tả trường:

  • id (Chuỗi): ID người dùng Telegram
  • first_name (Chuỗi): Tên người dùng
  • last_name (String): Họ của người dùng, tùy chọn
  • username (Chuỗi): Tên người dùng Telegram, tùy chọn
  • photo_url (Chuỗi): URL Avatar, tùy chọn
  • auth_date (Number): Dấu thời gian xác thực
  • hash (String): Băm xác minh Telegram

Ràng buộc tài khoản Telegram

  • Tên giao diện:Ràng buộc tài khoản Telegram
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/telegram/bind
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Liên kết tài khoản Telegram với tài khoản người dùng hiện có

💡 Ví dụ yêu cầu:

// passTelegramLoginButtonComponent automatically handles parameters
// The parameter format is the same asTelegramLogin same
const response = await fetch('/api/oauth/telegram/bind', {
  method: 'GET',
  params: telegram_auth_params
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "TelegramAccount binding successful!"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "ShouldTelegramAccount has been bound"
}

🧾 Mô tả trường:

Định dạng tham số giống với giao diện đăng nhập Telegram

Nhận trạng thái ngẫu nhiên (Anti-CSRF)

  • Tên giao diện:Nhận trạng thái ngẫu nhiên
  • Phương thức HTTP: NHẬN
  • Đường dẫn:/api/oauth/state
  • Yêu cầu xác thực:Công khai
  • Mô tả chức năng:Tạo tham số trạng thái ngẫu nhiên để bảo vệ CSRF trong luồng OAuth

💡 Ví dụ yêu cầu:

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();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": "random_state_string_12chars"
}

❗ Ví dụ về phản hồi thất bại:

{
  "success": false,
  "message": "generatestatefail"
}

🧾 Mô tả trường:

  • aff (String): Tùy chọn, tham số mã giới thiệu, dùng để ghi nguồn người dùng
  • data (String): Chuỗi trạng thái ngẫu nhiên được trả về, dài 12 ký tự