Contrat API — Topologie J+RADIUS

Version : 1.0 Base URL : https://live.jmoai.net/api/v1/radius Public : application mobile du client titulaire d’une licence J+RADIUS active.

Authentification et périmètre

Toutes les routes ci-dessous exigent le JWT du client. Le tenant est déduit du jeton : le client ne fournit jamais de client_id et ne peut ni voir ni promouvoir le NAS d’un autre client.

Un routeur est un NAS RADIUS lié à son allocation VPN canonique. Un NAS MEMBER reste un routeur RADIUS complet : il authentifie ses propres sessions. Le rôle PRIMARY est le routeur de référence des écritures de catalogue ; il ne redirige ni ne concentre le trafic RADIUS des secondaires.

Lire la topologie

GET /topology

Réponse 200 :

{
  "success": true,
  "primary": {
    "id": "uuid",
    "nasname": "10.42.0.2",
    "role": "PRIMARY",
    "status": "ACTIVE",
    "tunnel_status": "CONNECTED",
    "sessions_open": 4,
    "eligibility": { "eligible": true, "code": "ELIGIBLE" }
  },
  "members": [],
  "warnings": []
}

• primary vaut null lorsqu’aucun NAS actif n’est enregistré.
• members contient les NAS actifs non primaires.
• Une valeur eligibility.eligible: false ou une entrée warnings est une anomalie à afficher et à corriger ; ce n’est pas un routeur opérationnel.

Promouvoir un routeur secondaire

PUT /nas/:nasId/primary

nasId doit être un NAS actif du client authentifié. Aucun body n’est requis.

Réponse 200 :

{
  "success": true,
  "nas_id": "uuid",
  "role": "PRIMARY",
  "previous_primary_nas_id": "uuid",
  "changed": true
}

La bascule est atomique : le serveur garantit qu’il n’existe jamais deux NAS PRIMARY pour le même client. L’application ne doit pas essayer de gérer cette concurrence.

Erreurs :

Supprimer un routeur

DELETE /nas/:nasId

Avant de supprimer le PRIMARY alors qu’un ou plusieurs secondaires actifs existent, l’application doit d’abord promouvoir le secondaire choisi avec PUT /nas/:nasId/primary.

Sinon le serveur répond 409 :

{
  "error": "Ce NAS est le routeur principal. Désignez d abord un routeur secondaire comme principal.",
  "code": "PRIMARY_NAS_REASSIGN_REQUIRED",
  "details": {
    "primary_nas_id": "uuid",
    "candidate_nas_ids": ["uuid"]
  }
}

La suppression du dernier NAS actif est admise ; la prochaine inscription d’un NAS actif le désigne automatiquement PRIMARY.

Règles d’interface recommandées

• Afficher le primaire et les secondaires à partir de GET /topology, pas d’un cache local.
• Proposer la promotion avant le bouton de suppression du primaire.
• Après une promotion ou une suppression réussie, recharger GET /topology.
• Une liste vide ou primary: null est un état normal après désinstallation du dernier routeur : ne pas afficher une erreur de paiement ou de compte.

Écart volontaire

Le primaire n’est pas un concentrateur ni un point de défaillance RADIUS : chaque NAS reste enregistré et authentifie localement via FreeRADIUS. Ce choix évite de créer un routage inter-routeurs ou une isolation fournisseur implicite non validée.