Clés d’API

• Type non défini

Formation

Une clé API permet à une application ou à une automatisation d’accéder aux services Immersive avec les droits d’un compte associé. Elle évite de demander un mot de passe et un code MFA à chaque intervention d’un programme.

Ce tutoriel explique comment créer, consulter, prolonger et supprimer les clés depuis RestFrontage. Il s’adresse à l’administrateur Cerebrate. Les exemples d’appels WebAPI et d’authentification par le code seront traités dans un article distinct.

Les captures montrent l’interface RestFrontage dans un environnement de démonstration. Les clés illustrées n’ouvrent aucun accès à votre environnement.

1. Comprendre le principe

1.1 Une identité pour une application

Une application de supervision, un outil d’import ou une tâche planifiée doit pouvoir accéder à Immersive sans attendre qu’une personne saisisse un code sur son téléphone. Une clé API sert à authentifier cet accès automatisé.

Chaque clé est associée à :

• un nom d’application, qui permet d’identifier son usage ;
• un compte Immersive, dont elle utilise les droits ;
• une période de validité, avec une date de début et une date de fin ;
• un état activé ou désactivé.

La clé ne donne pas automatiquement tous les droits. Si le compte associé peut consulter une ressource mais pas la modifier, l’application reste soumise à cette restriction.

flowchart TD
    A["L’application présente son nom et sa clé API"] --> B["Vérifier la clé, ses dates et le compte associé"]
    B -->|Échec| R["Accès refusé"]
    B -->|Succès| D["Appliquer les droits du compte à la demande"]
    D -->|Droits insuffisants| F["Opération refusée"]
    D -->|Droits suffisants| G["Opération autorisée"]

1.2 Quel rapport avec la MFA ?

La MFA protège les connexions interactives par identifiant et mot de passe. La clé API est un autre moyen d’authentification, destiné aux programmes : aucun code TOTP n’est demandé lors de son utilisation.

Il n’est donc pas nécessaire d’exempter le compte de MFA pour permettre à une application d’utiliser sa clé API. La connexion habituelle de ce compte reste soumise au mode MFA choisi dans Immersive.

1.3 Choisir le compte associé

Utilisez de préférence un compte dédié à l’application, avec uniquement les droits nécessaires. Dans ce guide, Supervision atelier utilise Compte API - Supervision.

Le nom d’application n’est ni un utilisateur ni un groupe de permissions. C’est le compte associé qui porte les droits. Associer une clé à Cerebrate lui donnerait les droits de Cerebrate ; ce choix est à réserver aux usages qui en ont réellement besoin.

Le compte doit rester disponible : il ne doit pas être désactivé, supprimé, expiré ou temporairement verrouillé. Une clé encore valide ne permet pas de contourner l’indisponibilité du compte.

2. Ouvrir la gestion des clés

Connectez-vous à RestFrontage avec Cerebrate, ouvrez Sécurité, puis Clés API, reconnaissable à son icône de clé. L’adresse de la page est /Security/ApiKeys.

Dans l’interface actuelle, cette page et ses opérations de gestion sont réservées à Cerebrate.

La page affiche le nombre de clés et le nombre de clés actives. Chaque ligne présente le nom d’application, le compte associé, les derniers caractères de la clé, sa période de validité et son origine. Les derniers caractères aident à distinguer les clés ; ils ne remplacent pas la valeur complète.

Le champ Rechercher une application ou un compte filtre la liste. Cliquez sur une ligne pour ouvrir sa fiche.

2.1 Comprendre les états

État	Signification
Active	La clé est activée, sa période de validité est en cours et le compte associé est disponible. Les droits du compte continuent de s’appliquer à chaque opération.
À venir	La date de début n’est pas encore atteinte. La clé ne peut pas encore être utilisée.
Expirée	La date de fin est atteinte ou dépassée. La clé ne permet plus de s’authentifier.
Désactivée	La clé n’est pas activée. Elle ne peut pas être utilisée.
Compte indisponible	Le compte associé est introuvable, désactivé, supprimé, expiré ou temporairement verrouillé.

L’état résume la situation au chargement de la liste. Actualisez la page après une intervention extérieure ou pour vérifier une échéance qui vient d’être atteinte. Plusieurs causes peuvent coexister ; consultez aussi les dates et le compte associé.

2.2 Deux origines dans la même liste

Origine	Gestion possible depuis le site
Base Security	Clé créée depuis cette interface. Vous pouvez consulter sa fiche, afficher sa valeur lorsqu’elle est disponible, prolonger sa date de fin et la supprimer.
Appsettings · Lecture seule	Clé définie dans la configuration du serveur. Vous pouvez consulter sa fiche et afficher sa valeur disponible. Sa modification ou sa suppression relève de l’exploitant, dans la configuration.

Les clés de configuration ne sont pas automatiquement transformées en clés gérées depuis le site. Les deux origines peuvent coexister.

3. Créer une clé API

3.1 Renseigner l’application et choisir son compte

1. Cliquez sur Créer une clé API.
2. Dans Nom de l’application, saisissez un nom reconnaissable, par exemple Supervision atelier.
3. Cliquez sur le lien Choisir un utilisateur.
4. Dans la fenêtre de recherche, trouvez le compte à associer et sélectionnez-le.
5. Vérifiez que son nom apparaît dans Compte associé.

La sélection ouvre une seconde fenêtre sans perdre les informations déjà saisies. Le lien portant ensuite le nom du compte permet de choisir un autre utilisateur avant la création.

3.2 Définir les dates et enregistrer

1. Vérifiez le Début de validité.
2. Choisissez la Fin de validité, postérieure au début et située dans le futur.
3. Laissez Clé activée cochée pour une clé destinée à être utilisable pendant cette période.
4. Cliquez sur Créer la clé.
5. Attendez le message La clé API a été enregistrée.

Les dates sont affichées dans le fuseau horaire du navigateur. À l’ouverture du formulaire, une période d’environ un an est proposée ; adaptez-la au besoin réel de l’application. Pour préparer un accès futur, choisissez une date de début ultérieure.

La valeur de la clé est générée automatiquement : vous n’avez ni mot de passe à inventer ni code MFA à fournir pour l’application.

4. Consulter, afficher et copier la clé

4.1 Ouvrir les propriétés

Cliquez sur la ligne de la clé dans la liste. La fenêtre Propriétés de clé d’API présente le nom d’application, le compte associé, l’origine, l’état activé et les dates.

La clé est masquée par défaut, même lorsque vous revenez sur sa fiche. Les points visibles ne sont pas sa valeur et ne permettent pas de déduire sa longueur.

4.2 Afficher puis copier

1. Cliquez sur Afficher.
2. Attendez que la valeur apparaisse. Pendant le chargement, une animation remplace le texte du bouton.
3. Utilisez l’icône de copie à droite du champ pour copier la valeur complète.
4. Collez-la dans l’emplacement protégé prévu par l’application cliente.
5. Cliquez sur Masquer lorsque vous avez terminé.

La clé visible dans cette capture appartient uniquement à l’environnement de démonstration utilisé pour les illustrations. Elle a été supprimée à l’issue des captures.

L’icône de copie apparaît uniquement lorsque la clé est affichée. Si le champ est trop court pour montrer toute la valeur, utilisez cette icône : elle copie la clé complète. Masquer retire la valeur de l’écran, mais n’efface pas ce qui a déjà été copié dans le presse-papiers.

4.3 Quelles informations transmettre à l’application ?

L’intégrateur a besoin de l’adresse du serveur Immersive, du nom d’application enregistré et de la clé API complète. Le nom correspond à x-app-name et la clé à x-api-key dans les échanges API.

Le mot de passe du compte associé et les codes de son application MFA ne sont pas nécessaires pour cet accès par clé. Les requêtes et la gestion des jetons d’accès seront détaillées dans l’article WebAPI.

5. Prolonger la période de validité

Pour une clé d’origine Base Security, la prolongation permet de conserver la même valeur tout en repoussant sa date de fin.

1. Ouvrez la fiche de la clé.
2. Dans Prolonger jusqu’au, choisissez une date postérieure à la fin actuelle et située dans le futur.
3. Cliquez sur Prolonger.
4. Vérifiez le message La date de fin a été prolongée. et la nouvelle date affichée.

La prolongation ne change ni le nom d’application, ni le compte associé, ni la valeur de la clé. Elle ne permet pas de raccourcir la durée de validité.

Une clé expirée peut être prolongée vers une date future. Elle redevient utilisable si elle est activée, si son début de validité est atteint et si le compte associé est disponible. La prolongation ne réactive pas un compte désactivé.

6. Consulter une clé issue d’appsettings

Les clés portant Appsettings · Lecture seule proviennent de la configuration du serveur.

Vous pouvez ouvrir leurs propriétés et afficher leur valeur lorsqu’elle est disponible. La fiche ne propose ni Prolonger, ni Supprimer cette clé.

Pour les modifier, les retirer ou repousser leur échéance, contactez la personne qui exploite la configuration du serveur. Ne créez pas une autre clé en pensant que cela remplacera automatiquement celle d’appsettings : les deux accès resteraient distincts.

7. Supprimer ou remplacer une clé

7.1 Supprimer un accès devenu inutile

1. Ouvrez la fiche de la clé d’origine Base Security.
2. Cliquez sur Supprimer cette clé.
3. Vérifiez le nom d’application et le compte dans la fenêtre de confirmation.
4. Cliquez sur Supprimer la clé pour confirmer, ou sur Annuler pour conserver l’accès.
5. Vérifiez le message de suppression et la disparition de la ligne dans la liste.

La suppression est définitive. La clé et les jetons obtenus avec elle sont révoqués : ils ne permettent plus de nouveaux accès. Les données déjà consultées ou copiées par l’application ne sont pas effacées par cette action.

7.2 Remplacer une clé sans interrompre un usage prévu

Pour un renouvellement planifié, vous pouvez créer une nouvelle clé pour la même application et le même compte, avec une période de validité adaptée. Plusieurs clés peuvent coexister pour le même nom d’application.

flowchart TD
    A["Créer une nouvelle clé"] --> B["Configurer l’application avec la nouvelle clé"]
    B --> C["Vérifier un accès et les opérations nécessaires"]
    C --> D{"Le fonctionnement est-il confirmé ?"}
    D -->|Non| E["Corriger la configuration ou les droits"]
    E --> C
    D -->|Oui| F["Supprimer l’ancienne clé"]

Repérez les deux clés grâce à leurs dates et à leurs derniers caractères, afin de supprimer la bonne. La nouvelle clé ne désactive pas l’ancienne automatiquement.

8. Résoudre les difficultés courantes

8.1 Le compte sélectionné est désactivé

La création est refusée et un message indique le compte concerné. Dans l’exemple suivant, Eric T. est désactivé.

Choisissez un compte actif adapté à l’application. Si la réactivation du compte sélectionné est réellement souhaitée, effectuez-la d’abord dans sa fiche utilisateur, puis recommencez la création. Ne réactivez pas un compte désactivé volontairement uniquement pour faire disparaître le message.

Une erreur de validation ne crée pas la clé. Le formulaire conserve les informations saisies pour permettre la correction.

8.2 La clé existe, mais l’application n’accède pas aux données

Vérifiez successivement l’état de la clé, ses dates, le compte associé, le nom d’application et la valeur complète copiée. Vérifiez aussi que l’application utilise le bon serveur Immersive.

Si l’authentification réussit mais qu’une opération est refusée, examinez les droits du compte associé sur la ressource demandée. Créer une nouvelle clé pour le même compte ne lui attribue pas davantage de droits.

8.3 Autres messages et situations

Situation	Action à effectuer
Compte expiré	Vérifier si son usage doit être prolongé dans la fiche utilisateur, ou sélectionner un autre compte actif.
Date de fin refusée	À la création, choisir une fin future et postérieure au début. Pour une prolongation, choisir aussi une date postérieure à la fin actuelle de la clé.
La valeur de cette ancienne clé n’a pas été conservée	La clé existante reste utilisable, mais sa valeur ne peut pas être réaffichée. Si elle est perdue, créer une nouvelle clé, mettre à jour l’application et retirer l’ancienne.
La clé ne peut pas être déchiffrée sur ce serveur	Faire vérifier les clés de protection du serveur par l’exploitant. Cette erreur de consultation ne modifie pas, à elle seule, l’accès API.
Cette clé a été modifiée ou supprimée	Fermer la fiche et actualiser la liste avant de recommencer. Une autre intervention a pu modifier son état.
L’enregistrement n’a pas pu être confirmé	Actualiser la liste et vérifier le résultat avant de réessayer, afin d’éviter une création en double.
Le bouton de copie n’apparaît pas	Cliquer d’abord sur Afficher. Le bouton est volontairement absent lorsque la clé est masquée.

Pour les nouvelles clés consultables, le serveur conserve une valeur protégée permettant leur réaffichage. L’exploitant doit conserver les éléments de protection nécessaires lors des sauvegardes et changements de serveur. Ce point ne demande aucun nouveau mot de passe à l’utilisateur.

9. Vérifier la mise en service

Avant de confier une clé à une application, vérifiez ces points :

• le nom d’application est reconnaissable ;
• le compte associé est actif et possède uniquement les droits nécessaires ;
• la période de validité correspond à l’usage prévu ;
• l’application utilise le bon serveur, le bon nom et la clé complète ;
• un accès et les opérations attendues ont été vérifiés depuis l’application ;
• la clé est conservée dans un emplacement protégé et sa date d’expiration est suivie ;
• les anciennes clés devenues inutiles ont été retirées après le remplacement.