Control API à tenantadministration

FoxIDs dispose de surfaces Control API distinctes pour les opérateurs de déploiement qui administrent tenants et pour un tenant qui administre son propre compte. Utilisez les opérations de l'opérateur pour le provisionnement tenant et l'administration croiséetenant. Utilisez les opérations en libre-service lorsqu'une intégration doit être limitée à son propre tenant.

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 tenant propriétés, options de forfait et de paiement, règles de validation et schémas de réponse :

API surfaces

Opérateur de déploiement

Les opérations des opérateurs sont appelées dans le master tenant :

https://control.foxids.com/api/master/master

Opération	Point de terminaison	But
Liste	`GET /!tenants`	Répertoriez les non-master tenants avec des filtres et une pagination facultatifs.
Obtenir	`GET /!tenant?name={name}`	Lisez la ressource d'administration de tenant.
Créer	`POST /!tenant`	Provisionnez un tenant, un administrateur initial et des ressources par défaut.
Mise à jour	`PUT /!tenant`	Remplacez les propriétés tenant modifiables gérées par l'opérateur.
Supprimer	`DELETE /!tenant?name={name}`	Supprimez définitivement un tenant et toutes les données tenant.

Ces opérations nécessitent des droits d'accès master-tenant. Ils sont destinés à l'administration de déploiement fiable et aux services de provisionnement SaaS.

Tenant libre-service

Un tenant appelle ses propres opérations via son environnement master :

https://control.foxids.com/api/{tenant_name}/master

Opération	Point de terminaison	But
Obtenir	`GET /!mytenant`	Lisez le compte tenant de l'appelant et les paramètres disponibles.
Mise à jour	`PUT /!mytenant`	Mettez à jour les propriétés libre-service autorisées.
Supprimer	`DELETE /!mytenant`	Supprimez définitivement les données tenant de l'appelant et toutes les données tenant.

Le libre-service utilise tenant droits d'accès et ne peut pas en administrer un autre tenant. Les modifications de forfait, les paramètres de paiement et les domaines personnalisés sont également soumis aux politiques configurées pour le déploiement.

Modifiez l'hôte dans ces exemples pour un déploiement auto-hébergé et envoyez le jeton d'accès dans l'en-tête Authorization: Bearer {access_token}.

Répertorier et identifier tenants

GET /!tenants accepte filterName, filterCustomDomain et paginationToken. Lorsque les deux filtres sont fournis, un tenant est renvoyé lorsque son nom ou son domaine personnalisé correspond. Les enregistrements master tenant et tenant à usage interne uniquement ne sont pas inclus.

Répétez une requête paginée avec les mêmes filtres et le jeton opaque renvoyé jusqu'à ce qu'aucun jeton ne soit renvoyé. N'interprètez ni ne modifiez pas le jeton.

Le tenant name minuscule est l'identifiant stable utilisé dans les URL FoxIDs et Control API. Traitez-le comme une clé d’automatisation immuable. Un domaine personnalisé est une propriété de routage et de personnalisation distincte et ne doit pas être utilisé comme nom de Control APIroute tenant.

Provisionner un tenant

La création de Tenant est une opération de provisionnement composée. Une demande réussie crée :

l'enregistrement tenant ;
l'environnement master de tenant et sa méthode d'authentification de connexion par défaut ;
l'utilisateur administrateur initial ;
la ressource Control API et l'application Control Client ;
les environnements par défaut configurés du déploiement.

L'administrateur initial peut recevoir un mot de passe fourni ou établir un mot de passe via le flux de messagerie configuré. Protégez tout mot de passe fourni et n'enregistrez pas le corps de la demande.

La demande peut également sélectionner un plan et initialiser les paramètres du client, des réclamations et du domaine personnalisé lorsque le déploiement le permet. L'unicité du nom Tenant, les règles du plan, la prise en charge des domaines personnalisés et les données d'administrateur requises sont validées avant la fin du provisionnement. Si une erreur de compte ou de données interrompt le provisionnement, FoxIDs tente de nettoyer les ressources créées par cette requête ; néanmoins, les clients doivent traiter tout échec comme un échec et vérifier l'état avant de réessayer avec le même nom tenant.

Mettre à jour les paramètres tenant

Les opérations Tenant PUT sont des mises à jour complètes, pas des correctifs. Obtenez la ressource actuelle, conservez toutes les propriétés modifiables qui doivent rester inchangées, appliquez la modification souhaitée et envoyez le modèle de demande complet pour l'opérateur ou le point de terminaison libre-service sélectionné.

La ressource opérateur comprend des propriétés gérées par le déploiement telles que l'attribution du plan, la vérification du domaine personnalisé, la configuration de l'utilisation et du paiement, la devise, la TVA, le prix horaire et les données client. La ressource en libre-service expose uniquement les paramètres que tenant est autorisé à gérer.

La modification d'un domaine personnalisé via le libre-service marque le domaine comme non vérifié jusqu'à ce que la vérification requise soit terminée. Le plan sélectionné doit prendre en charge un domaine personnalisé. Utilisez l'opérateur API pour gérer l'état de vérification ; ne laissez pas un client tenant non fiable affirmer que son propre domaine est vérifié.

Supprimer un tenant

La suppression de Tenant est irréversible et en cascade. Il supprime tous les environnements de tenant ainsi que toutes les applications, méthodes d'authentification, utilisateurs, sessions, autorisations, clés et autres données FoxIDs. Il supprime également la configuration au niveau tenant et le routage de domaine personnalisé. Le master tenant ne peut pas être supprimé. Les journaux déjà envoyés vers un référentiel externe restent soumis à la politique de conservation et de suppression de ce référentiel.

Avant la suppression, arrêtez le trafic, exportez la configuration ou les données qui doivent être conservées, annulez ou rapprochez la facturation externe le cas échéant, et vérifiez le nom technique du tenant. Exiger une confirmation explicite dans les outils de l’opérateur. N'utilisez pas la suppression tenant pour désactiver temporairement l'accès ; désactivez ou mettez à jour les utilisateurs, applications ou méthodes d'authentification concernés.

Conseils en matière d'automatisation et de sécurité

Préférez les points de terminaison en libre-service lorsqu'un client n'a besoin que de gérer son propre tenant.
Limitez les informations d’identification de l’opérateur à un petit service de provisionnement fiable.
Conservez le nom technique tenant stable et stockez-le indépendamment des données d'affichage, de client et de domaine personnalisé.
Utilisez get-modify-put afin que les nouvelles propriétés ne soient pas réinitialisées par une ancienne intégration.
Utilisez la pagination pour tenant inventaires et effectuez le rapprochement par nom technique.
Traitez la création et la suppression de tenant comme des actions d'administration composées de longue durée ; utilisez les délais d'attente client appropriés et vérifiez l'état final après une réponse interrompue.
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 Request lorsque tenant, les données de l'administrateur, du forfait, du paiement, du client ou du domaine personnalisé ne sont pas valides.
401 Unauthorized lorsque le jeton d'accès est manquant ou invalide.
403 Forbidden lorsque l'appelant ne dispose pas du droit d'accès master ou tenant requis.
404 Not Found lorsque le tenant sélectionné n'existe pas.
409 Conflict lorsqu'un nom tenant ou une autre valeur unique existe déjà.

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.