Connecteurs personnalisés

Le catalogue couvre plus de 100 services, mais chaque équipe possède quelques outils internes ou produits SaaS régionaux qui n'y figurent pas. Les connecteurs personnalisés résolvent cela.

Vous enregistrez un identifiant — une clé API ou des identifiants OAuth — et vous indiquez à Zero comment appeler le service. À partir de là, Zero traite votre connecteur personnalisé exactement comme un connecteur intégré : même journal d'audit, même proxy d'accès intermédié, mêmes verrous sur les actions sensibles.

Deux variantes

Choisissez le type qui correspond à votre service :

• Clé API — fonctionne pour tout service qui s'authentifie avec un jeton statique dans un en-tête. Le chemin le plus simple et le plus rapide : collez la clé, nommez le connecteur, pointez Zero vers l'URL de base. La plupart des API internes et de nombreux outils SaaS utilisent cette méthode.
• OAuth 2.0 — pour les services qui émettent des jetons par utilisateur via OAuth. Vous fournissez un client ID et un secret, vous configurez les portées (scopes) que Zero doit pouvoir demander, et Zero exécute la danse OAuth par utilisateur lorsque nécessaire.

Si vous ne savez pas laquelle utiliser, consultez la documentation d'API du service en amont. Le terme « clé API » (ou « personal access token ») désigne généralement la variante 1 ; « OAuth » (ou « client credentials ») désigne généralement la variante 2.

Configurer un connecteur à clé API

1. Ouvrez la page Connecteurs de votre espace de travail.
2. Cliquez sur Ajouter un connecteur personnalisé → Clé API.
3. Renseignez :
   • Nom. Quelque chose que Zero pourra reconnaître à la lecture des prompts, par ex. internal-billing-api ou acme-crm.
   • URL de base. La racine de l'API : https://api.internal.acme.com.
   • En-tête d'authentification. Généralement Authorization: Bearer YOUR_TOKEN ou X-API-Key: YOUR_TOKEN. Faites correspondre à ce qu'attend le service.
   • Clé API. Collez l'identifiant. Stocké chiffré ; jamais visible après l'enregistrement.
   • Chemins autorisés (facultatif). Restreignez Zero à des endpoints précis, comme /v1/invoices/*. Réduit la surface d'exposition.
4. Cliquez sur Enregistrer puis Tester la connexion. Zero interroge l'URL de base avec un GET / (ou un chemin que vous spécifiez) et rapporte la réponse.

Configurer un connecteur OAuth 2.0

Un peu plus de travail, mais cela en vaut la peine pour les services où l'autorisation par utilisateur compte :

1. Enregistrez une application OAuth auprès du service en amont. Vous obtiendrez un client ID et un client secret. Définissez l'URI de redirection sur celle que VM0 affiche sur le formulaire d'ajout de connecteur.
2. Dans VM0 : Ajouter un connecteur personnalisé → OAuth 2.0.
3. Renseignez :
   • Nom et URL de base, comme ci-dessus
   • URL d'autorisation et URL de jeton issues de la documentation OAuth du service en amont
   • Client ID et Client secret
   • Portées (scopes). La liste des portées que Zero est autorisé à demander. Utilisez le minimum couvrant vos workflows.
4. Enregistrez. La première session qui a besoin de ce connecteur déclenche le flux OAuth par utilisateur.

Indiquer à Zero comment utiliser un connecteur personnalisé

Deux façons de faire. Choisissez celle qui convient à votre workflow.

Décrivez-le en ligne lorsque vous demandez quelque chose à Zero :

« Utilise le connecteur internal-billing-api pour récupérer la facture #4422. Puis envoie le PDF par e-mail à ops@acme.com. »

Zero charge la spécification du connecteur et détermine quel endpoint appeler. Cela fonctionne parce que les connecteurs sont accompagnés de métadonnées de type OpenAPI (auto-découvertes pour de nombreux services, fournies manuellement en option).

Écrivez une compétence qui référence le connecteur par son nom. Le corps de la compétence décrit la procédure ; Zero charge automatiquement la compétence lorsque la description correspond à une requête entrante. Pour les workflows répétés, c'est plus propre que de tout redécrire en ligne à chaque fois.

Une compétence nommée pull-invoice avec la description « récupérer une facture depuis internal-billing-api et envoyer le PDF par e-mail » — une fois écrite, Zero l'invoque dès que quelqu'un demande une facture.

Spécifications OpenAPI et schémas en ligne

Zero fonctionne au mieux avec un connecteur personnalisé lorsqu'il connaît les endpoints, méthodes et paramètres disponibles. Trois façons de les fournir :

• Auto-découverte à partir du /openapi.json ou /swagger.json du service s'il en expose un. Il suffit de pointer Zero vers l'URL.
• Téléverser une spécification. Collez ou téléversez un OpenAPI 3 en YAML/JSON. Zero l'analyse et propose des métadonnées de type infobulle lors de la construction des appels.
• Descriptions en ligne. Pour les outils internes sans spécification, vous pouvez écrire une courte description markdown dans le corps du connecteur — endpoints, méthodes, exemples de payloads. Rudimentaire mais fonctionnel.

Sans spécification, Zero fonctionne quand même — il doit simplement deviner davantage la forme des paramètres. Pour les connecteurs personnalisés fréquemment utilisés, une spécification est vite rentabilisée.

Partage entre espaces de travail

Les connecteurs personnalisés sont par défaut délimités à l'espace de travail. Deux équipes d'une même organisation peuvent chacune maintenir leur propre connecteur personnalisé pour la même API interne. Pour les organisations qui veulent une configuration canonique unique :

• Connecteurs au niveau de l'organisation (enterprise). Disponibles sur les forfaits enterprise. Configurés une seule fois au niveau de l'organisation ; ils apparaissent dans chaque espace de travail de cette organisation. Recommandé pour les API internes utilisées par tous.
• Package de connecteur. Pour les très grandes organisations, l'équipe plateforme interne peut publier un connecteur personnalisé sous forme de package versionné ; les espaces de travail l'installent et récupèrent les mises à jour automatiquement.

Sécurité et limites de débit

• Identifiants. Chiffrés au repos avec des clés propres à l'espace de travail. Jamais visibles après l'enregistrement ; uniquement re-saisissables.
• Audit par appel. Chaque requête via un connecteur personnalisé apparaît dans le journal de session avec la méthode, l'URL, le code de statut et le temps.
• Limites de débit. Imposées par le service en amont. Zero gère les réponses 429 avec un backoff exponentiel jusqu'à une limite configurée par espace de travail.
• Chemins en liste blanche. Facultatif : restreindre Zero à des motifs d'URL précis. Réduit la surface d'exposition si une clé de connecteur est sur-privilégiée.
• Lecture seule par défaut. Un nouveau connecteur personnalisé est marqué en lecture seule. L'octroi d'un accès en écriture nécessite une configuration explicite par espace de travail.

Pièges courants

• Clés API trop larges. Si votre service le permet, générez une clé délimitée pour Zero plutôt que de réutiliser votre clé d'administration personnelle. Plus facile à faire tourner et à auditer.
• Schémas manquants. Sans spécification OpenAPI ni description en ligne, Zero devine la forme des paramètres. Cela fonctionne pour les cas simples et casse pour les objets imbriqués. Fournissez une spécification quand vous le pouvez.
• URL de base non testées. Cliquez toujours sur Tester la connexion après la configuration. Une erreur 401 ou 404 à ce stade vaut bien mieux qu'une 401 dans une session critique.
• Oubli de rotation. Programmez un rappel d'agenda pour faire tourner les clés chaque trimestre. La rotation d'une clé de connecteur se fait en un clic dans VM0 ; c'est la rotation en amont qui prend le plus de temps.

Et ensuite

• Voir Compétences pour capturer des workflows répétés de connecteurs personnalisés.
• Voir Permissions pour la gestion des identifiants de connecteurs personnalisés.
• Voir le Catalogue avant de créer un connecteur personnalisé — votre service est peut-être déjà pris en charge.