Jeton API

Un jeton API (token) permet à un logiciel tiers d'appeler les points d'accès API d'Omniscol au nom de l'école, en lecture et, si des points d'accès API d'écriture sont sélectionnés, en écriture.

C'est puissant — donc à manier avec précaution.

Génération

Un jeton est généré dans Partage (Import/Export > Partage). Vous fournissez :

• une clé (générée dans Omniscol, avec libellé et expiration éventuelle ; sa date d'expiration peut être modifiée plus tard),
• une portée : la liste des points d'accès API que ce jeton pourra appeler (ne donnez que ce qui est strictement nécessaire),
• éventuellement une expiration du jeton. Cette date est inscrite dans le JWT généré et ne peut pas être modifiée ensuite.

Supprimer la clé, ou atteindre son expiration, révoque immédiatement les jetons dérivés. Pour changer l'expiration d'un jeton individuel, générez un nouveau JWT.

Utilisation

Le jeton se transmet dans l'en-tête HTTP Authorization: Bearer <token>, ou (moins recommandé pour la production) dans l'URL via ?auth=<token>.

Bonnes pratiques

• Une clé par intégration — facilite la révocation indépendante.
• Scope minimal — ne cochez que les API nécessaires, pas tout par défaut.
• Expiration au bon niveau — utilisez l'expiration de la clé pour piloter une intégration dans la durée ; utilisez l'expiration du jeton pour un accès temporaire non modifiable.
• Rotation périodique — régénérez la clé tous les 6-12 mois.
• Pas dans Git — le jeton ne doit pas finir versionné dans un repo public. Utilisez les variables d'environnement de votre serveur.

Différence avec OIDC / SSO

Pour connecter des utilisateurs réels avec leur identité institutionnelle, utilisez OIDC / SSO. Le jeton API est destiné aux intégrations techniques serveur à serveur, pas à la connexion quotidienne des utilisateurs.