Authentifier une session API
Utilisez un compte Lexoh existant disposant des permissions nécessaires à votre intégration. Les requêtes protégées utilisent la session établie à la connexion.
POST
/v1/auth/login
Se connecter avec un compte existant
Envoyez username et password en JSON. Une connexion réussie retourne success, session, user, role et servers. Conservez la valeur session de façon sécuritaire.
Exemple de requête
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"username":"USERNAME","password":"PASSWORD"}'Exemple de réponse
Champs sélectionnés de la réponse; user, role et servers sont omis de cet exemple.
{
"success": true,
"session": "SESSION_TOKEN"
}
POST
/v1/device/list
Transmettre la session avec chaque requête
Utilisez l’en-tête SessionID présenté ci-dessous. Authorization: Bearer SESSION_TOKEN et le témoin session sont également acceptés. La valeur Bearer est un jeton de session, et non une clé API générée séparément. Le rôle du compte détermine l’accès à chaque opération.
Exemple de requête
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/device/list" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"page":1,"page_limit":25}'
POST
/v1/auth/mfa
Valider l’AMF lorsqu’elle est activée
Si user.mfa_enabled vaut true, transmettez le code courant avec la session avant d’utiliser les opérations protégées. Le champ JSON est token; code est également accepté. La connexion Google ou Microsoft configurée utilise /v1/auth/oauth2 pour établir une session; les en-têtes de session de ces exemples restent les mêmes.
Exemple de requête
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/mfa" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"token":"MFA_CODE"}'Exemple de réponse
{
"success": true,
"mfa_enabled": true
}
POST
/v1/auth/logout
Fermer la session
Transmettez SessionID à la déconnexion pour que le serveur supprime cette session. Ne vous limitez pas à effacer le jeton du côté client.
Exemple de requête
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/logout" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Exemple de réponse
{
"success": true,
"user": null,
"error": null
}Lire le statut HTTP et le corps de la réponse
La connexion retourne HTTP 400 pour un JSON invalide et HTTP 404 lorsque les identifiants ne sont pas acceptés. Les erreurs de validation AMF utilisent HTTP 400. Certains gestionnaires de ressources protégées retournent HTTP 500 avec success:false en cas de session absente ou de permissions insuffisantes; un échec d’authentification ne correspond pas systématiquement à HTTP 401.
Exemple de réponse
Exemple du gestionnaire de liste des appareils, avec HTTP 500.
{
"success": false,
"devices": null,
"error": "authentication required."
}Protéger les sessions et maîtriser le volume de requêtes
- Ne placez pas les mots de passe et les jetons de session dans le code source, les pages publiques ou les journaux.
- Utilisez les permissions nécessaires à l’intégration et validez l’AMF lorsqu’elle est activée.
- Utilisez la pagination et limitez les requêtes simultanées. Cette référence ne définit pas de quota fixe par heure, par jour ou de requêtes simultanées.