Control API - environnements
Utilisez le FoxIDs Control API pour répertorier, créer, configurer et supprimer des environnements dans un tenant. Un environnement est appelé un track dans Control API routes et schémas.
Avant d'appeler ces opérations, configurez Control API l'authentification et les droits d'accès. Swagger reste la référence exacte pour toutes les propriétés d'environnement, règles de validation et schémas de réponse :
Base de point de terminaison
L'administration de l'environnement est effectuée via l'environnement master de tenant. Les exemples utilisent FoxIDs Cloud :
https://control.foxids.com/api/{tenant_name}/master
Remplacez {tenant_name} par le nom technique de tenant. Changez l’hôte pour un déploiement auto-hébergé. Envoyez le jeton d'accès Control API dans l'en-tête Authorization: Bearer {access_token}.
Les opérations d'environnement nécessitent le tenant ou le droit d'accès à l'environnement correspondant. Les environnements renvoyés par les opérations de liste sont limités à ceux auxquels l'appelant peut accéder. Utilisez la Control API hiérarchie des droits d'accès pour accorder uniquement l'opération read, create, update ou delete requise.
Opérations environnementales
Les opérations d'environnement sont regroupées sous tenant tracks dans Swagger.
| Opération | Point de terminaison | But |
|---|---|---|
| Liste | GET /!tracks |
Répertoriez les environnements accessibles avec un filtrage et une pagination facultatifs. |
| Obtenir | GET /!track?name={name} |
Obtenez la configuration complète pour un environnement. |
| Créer | POST /!track |
Créez un environnement et sa méthode d'authentification de connexion par défaut. |
| Mise à jour | PUT /!track |
Remplacez la configuration de l'environnement modifiable. |
| Supprimer | DELETE /!track?name={name} |
Supprimer définitivement un environnement et ses données. |
Ajoutez chaque point de terminaison à la base de point de terminaison.
Répertorier et identifier les environnements
GET /!tracks accepte filterName et paginationToken. Le filtre correspond soit au name technique, soit au displayName, quel que soit le cas.
La réponse contient une collection data et un paginationToken opaque. Pour lire la page suivante, répétez la même requête avec le token renvoyé et le même filtre. Continuez jusqu'à ce que la réponse ne contienne plus de jeton. N'interprètez ni ne modifiez pas le jeton.
Le name technique identifie l'environnement dans les Control API URL et dans les opérations d'obtention, de mise à jour et de suppression ultérieures. Traitez-le comme une clé d'automatisation stable. Utilisez displayName pour le texte présenté aux administrateurs.
Créer un environnement
Les noms d'environnement sont en minuscules. Fournissez un name lorsqu'une intégration nécessite une URL prévisible, ou omettez-le et laissez FoxIDs générer un nom unique. Une demande doit contenir soit un nom, soit un nom d'affichage.
La création d'un environnement crée également la méthode d'authentification de connexion par défaut. Les autres applications, méthodes d'authentification, utilisateurs, clés et ressources d'environnement sont configurées séparément après la création.
Le plan tenant peut limiter le nombre d'environnements. Une demande de création peut donc échouer lorsque la limite est atteinte. Les opérations de création simultanées limitées par le plan peuvent renvoyer 423 Locked ; réessayez après un court délai.
Mettre à jour les paramètres d'environnement
PUT /!track est une mise à jour complète, pas un correctif. Obtenez d’abord l’environnement actuel, conservez toutes les propriétés qui doivent rester inchangées, appliquez les modifications prévues et envoyez la représentation modifiable complète.
Le name technique sélectionne l'environnement et n'est pas renommé par une mise à jour. Les paramètres modifiables incluent les détails d'affichage et de l'entreprise, la durée de vie de la séquence, le comportement de mappage des revendications, la protection contre les échecs de connexion, les politiques de mot de passe, l'intégration de mots de passe et d'annuaires externes et les domaines iframe autorisés. Certaines ressources associées, notamment les SMS, les e-mails, les mappages de revendications, les textes, les clés et les certificats, disposent de points de terminaison dédiés et ne sont pas remplacées via l'opération de l'environnement.
Les paramètres mis à jour sont utilisés par les requêtes suivantes après que FoxIDs invalide le cache de configuration de l'environnement.
Supprimer un environnement
La suppression d’un environnement est une opération irréversible en cascade. Il supprime la configuration de l'environnement et toutes les données liées à cet environnement, y compris ses applications, méthodes d'authentification, utilisateurs, sessions, autorisations, clés et autres ressources. Les liens d'autres environnements vers l'environnement supprimé sont également supprimés.
N'utilisez pas la suppression d'environnement pour effacer les ressources sélectionnées. Supprimez ou mettez à jour ces ressources individuellement lorsque l'environnement doit rester disponible. Avant de supprimer un environnement, arrêtez le trafic vers celui-ci, exportez toute configuration ou donnée qui doit être conservée et vérifiez le nom technique dans la demande.
Conseils d'automatisation
- Gardez les noms techniques stables et stockez-les séparément des noms d’affichage.
- Utilisez la pagination de liste même lorsqu'un tenant ne dispose actuellement que de quelques environnements.
- Utilisez un workflow get-modify-put pour éviter de réinitialiser involontairement les paramètres ajoutés dans une version FoxIDs plus récente.
- Créez des ressources dépendantes uniquement une fois la demande de création d'environnement réussie.
- Traitez la suppression comme une opération de démontage permanent et exigez une confirmation explicite dans les outils d'administration.
- Attendez-vous à ce que les demandes de création, de mise à jour et de suppression apparaissent dans le journal d’audit de contrôle. Les opérations de lecture ne sont pas écrites sous forme d’événements d’audit.
Réponses aux erreurs courantes
400 Bad Requestlorsque les données ou le nom de l'environnement ne sont pas valides, qu'un nom réservé est utilisé ou qu'une limite de plan est atteinte.401 Unauthorizedlorsque le jeton d'accès est manquant ou invalide.403 Forbiddenlorsque l'appelant ne dispose pas du droit d'accès requis.404 Not Foundlorsque l'environnement sélectionné n'existe pas.409 Conflictlorsqu'un environnement portant le même nom technique existe déjà.423 Lockedlorsqu'une opération de création limitée au plan est temporairement verrouillée.
Utilisez le corps de la réponse pour les détails de validation et Swagger UI pour les réponses déclarées par chaque opération.