88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
API Module Guide

Module de connexion tiers OAuth

Description des fonctionnalités

Le préfixe de l'interface est uniformément http(s)://<your-domain>

HTTPS doit être utilisé dans les environnements de production pour sécuriser les jetons d'authentification. HTTP n'est recommandé que pour les environnements de développement.

Prend en charge diverses méthodes de connexion OAuth telles que GitHub, OIDC, LinuxDO, WeChat et Telegram. Implémente la protection CSRF et la gestion des sessions, prenant en charge la liaison de compte et l'enregistrement automatique. Le frontend gère le processus OAuth via la redirection.

🔐 Aucune authentification requise

Redirection OAuth GitHub

  • Nom de l'interface：Redirection GitHub OAuth
  • Méthode HTTP：GET
  • Chemin：/api/oauth/github
  • Exigence d'authentification：Public
  • Description de la fonction：Gère le rappel GitHub OAuth pour terminer la connexion de l'utilisateur ou la liaison du compte

💡 Exemple de demande:

_// 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`;

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • code (String) : code d'autorisation GitHub OAuth, fourni par GitHub lors du rappel
  • state (String) : Code d'état anti-CSRF, doit correspondre à celui stocké dans la session

Redirection OAuth générale OIDC

  • Nom de l'interface：Redirection générale OAuth OIDC
  • Méthode HTTP：GET
  • Chemin：/api/oauth/oidc
  • Exigence d'authentification：Public
  • Description de la fonction: gère le rappel OIDC OAuth, prend en charge la connexion générale au protocole OpenID Connect

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • code (String) : code d'autorisation OIDC
  • state (String): code d'état anti-CSRF

LinuxDo Redirection OAuth

  • Nom de l'interface：Redirection LinuxDo OAuth
  • Méthode HTTP：GET
  • Chemin：/api/oauth/linuxdo
  • Exigence d'authentification：Public
  • Description de la fonction：Gère le rappel LinuxDo OAuth, prend en charge la connexion via le compte de la communauté LinuxDo

💡 Exemple de demande:

_// 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}`;

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • code (String): code d'autorisation LinuxDo OAuth
  • state (String): code d'état anti-CSRF
  • error (String) : Facultatif, code d'erreur OAuth
  • error_description (String): facultatif, description de l'erreur

Redirection de connexion par code QR WeChat

  • Nom de l'interface：Redirection de connexion au code QR WeChat
  • Méthode HTTP：GET
  • Chemin：/api/oauth/wechat
  • Exigence d'authentification：Public
  • Description de la fonction：Gère la connexion par code QR WeChat, termine le processus de connexion via le code de vérification

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

code (Chaîne): Code de vérification obtenu à partir du scan QR WeChat

Liaison de compte WeChat

  • Nom de l'interface：Liaison de compte WeChat
  • Méthode HTTP：GET
  • Chemin：/api/oauth/wechat/bind
  • Exigence d'authentification：Public
  • Description de la fonction：Lie le compte WeChat à un compte utilisateur existant

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

code (Chaîne): Code de vérification obtenu à partir du scan QR WeChat

Liaison par e-mail

  • Nom de l'interface ： Liaison par e-mail
  • Méthode HTTP：GET
  • Chemin：/api/oauth/email/bind
  • Exigence d'authentification：Public
  • Description de la fonction ： Lie une adresse e-mail au compte utilisateur via un code de vérification par e-mail

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • email (String) : Adresse email à lier
  • code (Chaîne): Code de vérification de l'e-mail

Connexion au télégramme

  • Nom de l'interface：Connexion au télégramme
  • Méthode HTTP：GET
  • Chemin：/api/oauth/telegram/login
  • Exigence d'authentification：Public
  • Description de la fonction ： Termine la connexion de l'utilisateur via Telegram Widget

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • id (Chaîne) : ID utilisateur Telegram
  • first_name (String) : Prénom de l'utilisateur
  • last_name (String) : Nom de l'utilisateur, facultatif
  • username (String): nom d'utilisateur Telegram, facultatif
  • photo_url (String): URL de l'avatar, facultatif
  • auth_date (Numéro): Horodatage d'authentification
  • hash (String): hachage de vérification du télégramme

Liaison de compte Telegram

  • Nom de l'interface ： Liaison de compte Telegram
  • Méthode HTTP：GET
  • Chemin：/api/oauth/telegram/bind
  • Exigence d'authentification：Public
  • Description de la fonction：Lie le compte Telegram à un compte utilisateur existant

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

Le format des paramètres est le même que celui de l'interface de connexion Telegram

Obtenir un état aléatoire (Anti-CSRF)

  • Nom de l'interface：Obtenir un état aléatoire
  • Méthode HTTP：GET
  • Chemin：/api/oauth/state
  • Exigence d'authentification：Public
  • Description de la fonction：Génère un paramètre d'état aléatoire pour la protection CSRF dans le flux OAuth

💡 Exemple de demande:

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

✅ Exemple de réponse réussie:

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

❗ Exemple de réponse en cas d'échec:

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

🧾 Description du champ:

  • aff (String): facultatif, paramètre de code de référence, utilisé pour enregistrer la source de l'utilisateur
  • data (String) : La chaîne d'état aléatoire renvoyée, longue de 12 caractères

Module d'authentification de courrier électronique

Page précédente

Module utilisateur

Page suivante

Sommaire

🔐 Aucune authentification requise
Redirection OAuth GitHub
Redirection OAuth générale OIDC
LinuxDo Redirection OAuth
Redirection de connexion par code QR WeChat
Liaison de compte WeChat
Liaison par e-mail
Connexion au télégramme
Liaison de compte Telegram
Obtenir un état aléatoire (Anti-CSRF)