Référence de l'API de liaison Steam
Pour ton serveur de jeu : obtenir un code de liaison pour un joueur, savoir quel membre Discord correspond à quel compte Steam, quel est son nom et ses rôles, et si le membre a le rôle de liaison. Des exemples prêts à adapter sont donnés pour Garry's Mod, FiveM, Rust, Counter-Strike 2 et SourceMod, et pour Python, Node.js, PHP et cURL.
Le principe
- Le joueur tape /link en jeu : ton serveur appelle POST /code avec son SteamID64 (celui que le jeu lui-même lui attribue) et lui affiche le code reçu.
- Il clique sur « Lier mon compte » dans Discord et tape le code : MoBot lie les deux comptes et donne le rôle choisi. Comme seul le joueur connecté en jeu connaît le code, la liaison prouve que la même personne tient les deux comptes.
- Ton serveur appelle POST /lookup pour savoir si un joueur est lié (et à quel membre Discord), comment il s'appelle sur Discord, quels rôles il a et s'il a le rôle de liaison : il peut donner un grade, un kit ou un nom de personnage.
Joueur Serveur de jeu API MoBot Discord
│ /link │ │ │
│──────────────────▶│ POST /code {steam_id} │ │
│ │──────────────────────────▶│ │
│ « Code K7M2QX » │ { code: "K7M2QX" } │ │
│◀──────────────────│◀──────────────────────────│ │
│ │
│ bouton « Lier mon compte » + code K7M2QX ─────────────────────────────▶│
│ │ │◀── MoBot lie les comptes │
│ │ │ et donne le rôle ────▶│
│ │ POST /lookup {steam_id} │ │
│ grade / kit │──────────────────────────▶│ │
│◀──────────────────│ { linked, roles, … }◀────│ │MoBot ne se connecte jamais à ton serveur de jeu : c'est ton serveur qui appelle l'API (il n'y a rien à ouvrir côté pare-feu). Pour savoir tout de suite qu'un joueur vient de se lier, ton serveur redemande /lookup toutes les 10 secondes tant que le code est valable (voir les exemples).
Démarrage en 5 minutes
- Dans le tableau de bord, ouvre le module Liaison Steam, active-le et choisis le ou les rôles à donner (ils doivent être sous le rôle de MoBot).
- Choisis le salon du panneau, enregistre, puis « Publier / mettre à jour le panneau » : les membres y trouvent le bouton « Lier mon compte ».
- Onglet Actions : « Générer une clé d'API ». Copie-la tout de suite, elle ne s'affiche qu'une fois.
- Teste la clé depuis un terminal avec la commande ping ci-dessous : tu dois voir le nom de ton serveur Discord. Le tableau de bord affiche ensuite l'heure du dernier appel de ton serveur de jeu.
- Copie l'exemple de ton jeu (plus bas), mets la clé dans la configuration de ton serveur, redémarre : /link donne un code en jeu.
curl -s -X POST https://mobot.adkynet.fr/api/v1/steam/ping -H "Authorization: Bearer mbsk_..." -H "Content-Type: application/json" -d "{}"
→ { "ok": true, "guild": { "id": "123…", "name": "Mon serveur" }, "linked_count": 0, "code_expires_in": 600, "role_ids": ["…"] }Authentification
Génère la clé dans le tableau de bord (module Liaison Steam › Actions et listes › « Générer une clé d'API »). Elle ne s'affiche qu'une fois. Envoie-la dans l'en-tête Authorization. Les adresses sont en HTTPS.
Authorization: Bearer mbsk_<identifiant du serveur>_<48 caractères>
Content-Type: application/json
URL de base : https://mobot.adkynet.fr/api/v1/steamChaque route accepte POST avec un corps JSON ; /lookup, /code, /links et /ping acceptent aussi GET avec les champs dans l'adresse (?steam_id=…), pour les serveurs qui ne savent faire que des GET. Un corps JSON doit toujours être un objet { } : une liste vide [ ] est refusée (certaines bibliothèques, comme celle de Garry's Mod, envoient [ ] pour une table vide).
POST /code
Donne un code à un joueur. Un nouveau code remplace l'ancien. Si le compte est déjà lié, aucun code n'est créé.
POST https://mobot.adkynet.fr/api/v1/steam/code
{ "steam_id": "76561198000000001" }
→ 200 { "linked": false, "code": "K7M2QX", "expires_in": 600 }
→ 200 { "linked": true, "steam_id": "7656…", "discord_id": "1234…", "linked_at": "2026-10-22T18:00:00+00:00" }Le code a 6 caractères, sans 0, O, 1 ni I (pour qu'on le recopie sans se tromper), la casse n'a pas d'importance, et sa durée est réglable de 2 à 60 minutes dans le module (« expires_in » est en secondes). Un membre a 5 essais par tranche de 10 minutes.
POST /lookup
Retrouve une liaison par SteamID64 ou par identifiant Discord, et indique si le membre est sur le serveur, son nom, ses rôles et s'il a le rôle de liaison. Les rôles sont des identifiants : copie-les dans Discord (clic droit sur le rôle › Copier l'identifiant, avec le mode développeur) pour les associer à un grade en jeu.
POST https://mobot.adkynet.fr/api/v1/steam/lookup
{ "steam_id": "76561198000000001" } (ou { "discord_id": "123456789012345678" })
→ 200 {
"linked": true, "steam_id": "…", "discord_id": "…", "linked_at": "…",
"in_server": true, "has_role": true,
"username": "alice", "display_name": "Alice",
"roles": ["555555555555555555", "777777777777777777"]
}
→ 200 { "linked": false }« has_role » est vrai quand le membre a tous les rôles de liaison du module. Si le membre a quitté le serveur, « in_server » est faux et les champs « username », « display_name » et « roles » sont absents (sa liaison est supprimée à son départ).
POST /unlink
Délie un compte (par exemple après un bannissement en jeu) ; le rôle est retiré si le réglage du module le demande.
POST https://mobot.adkynet.fr/api/v1/steam/unlink
{ "steam_id": "76561198000000001" }
→ 200 { "unlinked": true }POST /links
Toutes les liaisons du serveur, 100 par page : relance avec « after » = la valeur « next » de la page précédente.
POST https://mobot.adkynet.fr/api/v1/steam/links
{ "after": 0, "limit": 100 }
→ 200 { "links": [ { "id": 1, "steam_id": "…", "discord_id": "…", "linked_at": "…" } ], "next": 1 } (next = null à la dernière page)POST /ping
Teste la connexion : si la clé est bonne et le module activé, MoBot répond avec le nom du serveur Discord, le nombre de comptes liés, la durée de validité d'un code et les rôles de liaison. À lancer au démarrage du serveur de jeu pour détecter une clé périmée.
POST https://mobot.adkynet.fr/api/v1/steam/ping
{}
→ 200 { "ok": true, "guild": { "id": "123…", "name": "Mon serveur" }, "linked_count": 42, "code_expires_in": 600, "role_ids": ["555…"] }
→ 401 { "error": "invalid_key" }Trouver le SteamID64
L'API attend toujours un SteamID64 : 17 chiffres, qui commencent par 7656119. Voici où le prendre selon le jeu ; utilise toujours celui que le jeu t'annonce, jamais un identifiant saisi par le joueur.
| Jeu | Où le trouver |
|---|---|
| Garry's Mod | ply:SteamID64() |
| FiveM | L'identifiant « steam: » est en hexadécimal : tonumber(hex, 16) donne le SteamID64 (exemple FiveM ci-dessous). |
| Rust (Oxide / uMod) | player.UserIDString |
| Counter-Strike 2 | player.SteamID |
| TF2, CS:GO, L4D2… | GetClientAuthId(client, AuthId_SteamID64, …) |
| Autres jeux | Tout jeu qui expose l'identifiant Steam d'un joueur (ARK, 7 Days to Die, Unturned, Project Zomboid, Squad…) : cherche « SteamID64 » dans la documentation de son API de mods. |
| Minecraft | Minecraft n'utilise pas Steam : cette liaison ne le concerne pas. |
Si ton jeu donne un ancien format, voici la conversion (l'identifiant de compte est « Z×2 + Y » pour STEAM_X:Y:Z, et le nombre entre crochets pour [U:1:N]) :
SteamID64 = 76561197960265728 + identifiant de compte
STEAM_0:1:20000 → compte = 20000 × 2 + 1 = 40001 → 76561198000000001
[U:1:40001] → compte = 40001 → 76561198000000001Exemples par jeu
Chaque exemple fait la même chose : la commande /link donne un code au joueur, et à sa connexion le serveur relit sa liaison. Remplace la clé « mbsk_… » par celle de ton serveur Discord, et garde-la dans la configuration de ton serveur de jeu, jamais dans un fichier que tu partages.
/link donne un code, puis le serveur guette la liaison toutes les 10 secondes ; à la connexion, le grade est donné d'après le rôle Discord. Adapte SetUserGroup à ton système de grades (ULX, SAM, ServerGuard…).
Où ? Un fichier Lua côté serveur : garrysmod/addons/mobot_link/lua/autorun/server/mobot_link.lua. · Exemple à adapter à ton serveur : il suit la documentation du jeu mais n'a pas pu être lancé en jeu.
-- garrysmod/addons/mobot_link/lua/autorun/server/mobot_link.lua
local API = "https://mobot.adkynet.fr/api/v1/steam"
-- La clé est dans garrysmod/data/mobot_key.txt (une ligne) : jamais dans un addon que tu partages
local KEY = string.Trim(file.Read("mobot_key.txt", "DATA") or "")
-- Rôle Discord (identifiant) -> groupe en jeu : remplace SetUserGroup par l'appel de ULX, SAM, ServerGuard…
local GROUPS = {
["123456789012345678"] = "vip",
["234567890123456789"] = "moderator",
}
local function call(action, body, done)
HTTP({
url = API .. "/" .. action,
method = "POST",
type = "application/json",
body = util.TableToJSON(body), -- toujours au moins un champ : une table vide serait envoyée comme [] au lieu de {}
headers = { Authorization = "Bearer " .. KEY },
success = function(status, response) done(status, util.JSONToTable(response) or {}) end,
failed = function(reason) print("[MoBot] API injoignable : " .. tostring(reason)) end,
})
end
-- Donne au joueur le grade de son rôle Discord le plus haut dans la liste GROUPS
local function apply(ply, data)
if not (data.linked and data.in_server) then return end
ply:SetNWString("discord_id", data.discord_id)
ply:SetNWString("discord_name", data.display_name or "")
for _, roleId in ipairs(data.roles or {}) do
if GROUPS[roleId] then
ply:SetUserGroup(GROUPS[roleId])
break
end
end
end
-- /link : un code à taper sur Discord, puis on guette la liaison (un appel toutes les 10 s pendant la validité du code)
hook.Add("PlayerSay", "MoBotLink", function(ply, text)
if string.lower(string.Trim(text)) ~= "/link" then return end
if (ply.mobotNext or 0) > CurTime() then
ply:ChatPrint("Patiente quelques secondes avant de redemander un code.")
return ""
end
ply.mobotNext = CurTime() + 5
local steamId = ply:SteamID64()
call("code", { steam_id = steamId }, function(status, data)
if not IsValid(ply) then return end
if data.linked then
ply:ChatPrint("Ton compte est déjà lié.")
elseif data.code then
ply:ChatPrint("Ton code : " .. data.code .. " (valable " .. math.floor(data.expires_in / 60) .. " min). Clique sur « Lier mon compte » dans Discord.")
local timerName = "mobot_wait_" .. steamId
timer.Create(timerName, 10, math.floor(data.expires_in / 10), function()
if not IsValid(ply) then timer.Remove(timerName) return end
call("lookup", { steam_id = steamId }, function(_, found)
if found.linked and IsValid(ply) then
timer.Remove(timerName)
ply:ChatPrint("Compte lié, merci !")
apply(ply, found)
end
end)
end)
else
ply:ChatPrint("MoBot n'a pas répondu (" .. tostring(status) .. "), réessaie plus tard.")
end
end)
return ""
end)
-- À la connexion : le joueur est-il lié, et quel est son grade ?
hook.Add("PlayerAuthed", "MoBotCheck", function(ply)
call("lookup", { steam_id = ply:SteamID64() }, function(_, data)
if IsValid(ply) then apply(ply, data) end
end)
end)Bonnes pratiques
- Ne fais jamais confiance à un SteamID que le joueur te dit : prends celui que le jeu connaît. C'est ce qui rend la liaison fiable.
- Appelle l'API depuis ton serveur, jamais depuis le client du joueur : la clé donnerait accès à toutes les liaisons du serveur.
- Garde le résultat de /lookup quelques minutes (par joueur) plutôt que de le redemander à chaque action : l'API accepte environ 300 appels par minute.
- Pendant l'attente d'une liaison, un appel toutes les 10 secondes par joueur suffit ; arrête de demander quand le code expire (« expires_in »).
- Gère les échecs : si l'API ne répond pas (503) ou si tu es limité (429), le jeu doit continuer à fonctionner et réessayer plus tard, sans bloquer le joueur.
- Si la clé a fuité : « Révoquer la clé d'API » (ou en générer une nouvelle) dans le tableau de bord la coupe tout de suite. Les liaisons déjà faites restent.
Dépannage
| Symptôme | Cause probable et solution |
|---|---|
| 401 invalid_key | Clé fausse, copiée avec un espace ou un retour à la ligne, révoquée et remplacée, ou module désactivé. La réponse est la même dans tous les cas, par sécurité : lance /ping, vérifie que le module est activé, et regénère la clé si besoin. |
| 400 invalid_steam_id | Le SteamID n'a pas 17 chiffres. Sur FiveM, c'est l'identifiant hexadécimal qui a été envoyé : convertis-le en décimal. |
| 400 invalid_request | Le corps n'est pas un objet JSON (une liste vide [ ] par exemple), ou un champ est mal formé. |
| 429 rate_limited | Trop d'appels : mets les réponses en cache et attends le nombre de secondes de l'en-tête Retry-After. |
| « Code invalide ou périmé » sur Discord | Le code a expiré, ou un nouveau code l'a remplacé (seul le dernier fonctionne). Les lettres peuvent être tapées en minuscules ; 0, O, 1 et I n'existent pas dans les codes. |
| Le rôle n'est pas donné | Le rôle est au-dessus de celui de MoBot dans la liste des rôles, ou MoBot n'a pas « Gérer les rôles ». Place le rôle de MoBot au-dessus ; la page Diagnostic le vérifie. |
| has_role: false | Le membre n'a pas (ou plus) tous les rôles de liaison : ils ne sont donnés qu'à la liaison, et retirés à la déliaison si le réglage le demande. |
| linked: false | Le joueur n'a pas encore lié son compte, il a été délié (par lui, par l'équipe, ou en quittant le serveur Discord), ou ce n'est pas le même SteamID64. |
| Aucune réponse du tout | Le serveur de jeu n'arrive pas à joindre le site en HTTPS (pare-feu sortant, ancienne version de la bibliothèque TLS, serveur sans accès à Internet). Essaie la commande cURL depuis la même machine. |
Erreurs et limites
401 invalid_key— clé absente, fausse, révoquée, ou module désactivé (même réponse dans tous les cas).400 invalid_request / invalid_steam_id / invalid_json— champ mal formé : un SteamID64 fait 17 chiffres.429 rate_limited— trop de demandes (en-tête Retry-After). Environ 300 par minute et par adresse.503 unavailable— MoBot est momentanément injoignable : réessaie.