API Omniscol — jetons d'authentification

Clé et jeton : deux objets distincts

Omniscol distingue deux objets qu'il ne faut pas confondre.

Une clé est un objet persistant, conservé côté Omniscol. Elle réunit :

• un identifiant court, généré aléatoirement, public : c'est lui que la liste affiche, et il voyage dans chaque jeton pour désigner la clé à vérifier ;
• un libellé descriptif, modifiable à tout moment ;
• une date d'expiration facultative, modifiable à tout moment ;
• un secret aléatoire long, tiré côté serveur, qui sert de clé de signature cryptographique.

L'identifiant, le libellé et la date d'expiration sont des informations d'administration : l'identifiant n'est qu'une référence publique, pas un élément secret. Le secret, lui, est le seul matériel de signature : généré aléatoirement à la création de la clé, il reste côté serveur, n'est pas modifiable, et n'est jamais affiché ni renvoyé — ni à la création, ni dans la liste des clés. Et même s'il fuyait, il ne suffirait pas à forger un jeton : la signature le combine à un sel propre au compte et à un secret serveur qui, eux non plus, ne quittent jamais Omniscol.

Un jeton est un JWT (JSON Web Token) autonome, signé avec le secret de la clé. C'est lui que vous transmettez au système externe. Son contenu signé porte le compte concerné, la liste des points d'accès autorisés, la clé dont il dérive et sa propre date d'expiration.

Autrement dit : une clé signe, un jeton est signé. Une même clé peut signer plusieurs jetons — tous vérifiables avec le même secret, donc tous révoqués ensemble si la clé disparaît.

Omniscol ne stocke pas le jeton : il le génère, l'affiche une fois, puis le revérifie à chaque appel en reconstituant sa signature à partir du secret de la clé (HMAC SHA-256). Aucune autorisation portée par le jeton ne peut donc être altérée sans ce secret.

Créer un jeton

L'écran Partage est disponible dans Administration → Import / Export sur les comptes Premium. La création se fait en deux temps : on crée d'abord une clé, puis on génère un jeton à partir de cette clé.

1. Créer une clé — renseignez un libellé parlant et, si l'accès est temporaire, une date d'expiration. Son libellé et son expiration restent modifiables après coup ; son secret de signature, non.
2. Générer un jeton — sélectionnez la clé, cochez les points d'accès autorisés, choisissez éventuellement une date d'expiration propre au jeton, puis générez le JWT.

À la génération, Omniscol affiche le jeton une seule fois. Copiez-le immédiatement dans un gestionnaire de secrets : il ne sera plus ré-affiché. L'expiration du jeton est inscrite dans son contenu signé : elle ne se modifie pas a posteriori. Pour changer cette date, générez un nouveau jeton.

Il y a donc deux niveaux d'expiration, indépendants l'un de l'autre :

• expiration de la clé — modifiable depuis la liste des clés ; lorsqu'elle est atteinte, tous les jetons dérivés de cette clé sont refusés (l'appel échoue avec un 401) ;
• expiration du jeton — fixée à la génération, inscrite dans le JWT, et non modifiable ensuite.

Points d'accès autorisés

Un jeton ne donne accès qu'aux points d'accès cochés à sa génération : ne présumez jamais qu'il couvre toute l'API. La liste autorisée est transportée dans le jeton et vérifiée à chaque appel ; un appel vers un point d'accès non autorisé est refusé (401).

Au-delà des points d'accès individuels, la liste de sélection propose des raccourcis par module :

• l'entrée d'un module seul autorise tous ses points d'accès ;
• les variantes par opération — lecture, modification, création, suppression — restreignent le module à un seul type d'appel.

Cocher « EDT [lecture] » accorde ainsi toute la lecture des emplois du temps sans ouvrir la moindre écriture, sans cocher chaque point d'accès un par un. Restez au plus juste : n'accordez que les modules et les opérations strictement nécessaires à l'intégration.

Utiliser un jeton

Deux manières usuelles d'envoyer le jeton à l'API :

• En-tête HTTP : Authorization: Bearer <jeton> (recommandé).
• Query string : ?auth=<jeton> (pratique pour le debug, mais apparaît dans les logs HTTP — à éviter en production).

Exemple curl, à adapter avec un point d'accès réel issu de l'OpenAPI :

curl -H "Authorization: Bearer $TOKEN" \
  https://votre-ecole.omniscol.com/api/<module>/<point-acces>

Documentation OpenAPI

L'écran Import / Export affiche un lien OpenAPI 3.1 qui ouvre la spécification disponible pour le compte dans Swagger Editor. Vous y trouverez :

• la liste des points d'accès API exposés,
• les schémas des données échangées,
• les méthodes et paramètres,
• les réponses attendues.

La spécification est aussi servie directement par votre compte, sans authentification :

• /api/guest/openapi.json — spécification au format JSON ;
• /api/guest/openapi.yaml (ou /api/guest/openapi?yaml=true) — même contenu au format YAML ;
• /api/guest/school_schema.json — schéma JSON des données du compte.

Révoquer un accès

La révocation se fait au niveau de la clé, pas du jeton individuel.

L'écran liste les clés ayant servi à générer des jetons. Supprimer une clé efface son secret de signature côté Omniscol : dès lors, aucune signature dérivée de ce secret ne peut plus être vérifiée, et tout appel présentant un jeton issu de cette clé échoue avec un 401. C'est l'absence du secret qui invalide les jetons, pas une liste de révocation.

Pour la DSI, deux conséquences :

• Il n'y a pas de révocation jeton par jeton. Omniscol ne conserve pas les JWT émis et ne peut pas en désactiver un isolément : un jeton déjà généré reste valable jusqu'à sa propre expiration, ou jusqu'à ce que sa clé soit supprimée ou expirée.
• Modifier l'expiration d'une clé agit immédiatement sur tous ses jetons : avancer cette date coupe l'accès de l'ensemble des jetons issus de la clé.

Bonne pratique : supprimez sans attendre toute clé dont vous soupçonnez la fuite, puis recréez une clé de remplacement avec un libellé parlant.

Une clé par cible et par usage

Puisque la révocation est par clé, dédiez une clé à chaque intégration (un logiciel externe = une clé). Le secret d'une clé ne signe que ses propres jetons : supprimer cette clé n'invalide que les accès de l'intégration concernée, sans toucher aux autres.

À l'inverse, une clé unique partagée entre plusieurs systèmes rend toute révocation brutale : supprimer la clé compromise coupe d'un coup tous les systèmes qui s'en servaient.

Pour quelles intégrations

L'API est typiquement utilisée pour :

• systèmes de signage custom (au-delà des panneaux d'affichage Omniscol natifs ; voir Personnalisation des panneaux),
• dashboards externes consolidant Omniscol et d'autres sources,
• connecteurs ou synchronisations avec un ERP ou un SI métier,
• agents IA compatibles MCP consommant Omniscol via le serveur MCP ; voir MCP — connecter un agent IA externe.

Pour un accès délégué à un service tiers identifié (jeton scopé, consentement de l'utilisateur, révocable en désactivant le client), préférez le serveur OAuth2 d'Omniscol : voir OAuth2 / OIDC (fournisseur).