Aller au contenu

API cible et authentification

Mis à jour le 29 octobre 2026

L'API cible est l'API réelle que Voozeo appelle à chaque fois qu'une IA utilise un outil. Cette page explique comment la configurer.

URL de base

Dans l'onglet « API cible », le champ « URL de base » est l'adresse HTTPS publique de votre API, sans paramètres de requête ni fragment (https://api.example.com/v1, pas https://api.example.com/v1?x=1). Si votre spec en contient une, elle est proposée avec la mention « Issue de la spec » ; vous pouvez aussi saisir la vôtre. Une valeur saisie par vos soins n'est jamais écrasée par un nouvel import, et « Utiliser l'URL de la spec » permet d'y revenir. Sans URL de base, l'onglet vous invite à importer une spec ou à la saisir.

Authentification

Choisissez le type d'authentification attendu par votre API.

Aucune

Les appels partent sans identifiant. Convient aux API publiques.

Clé d'API

Renseignez le « Nom » de l'en-tête ou du paramètre (caractères de jeton HTTP : lettres, chiffres et les caractères !#$%&'*+-.^_|~ ou l'accent grave, 128 caractères au maximum), son « Emplacement » (« En-tête » ou « Paramètre de requête ») et le « Secret ». Par exemple, nom X-Api-Key en en-tête. Certains en-têtes, gérés par Voozeo, ne peuvent pas être utilisés.

Jeton Bearer

Saisissez le jeton : il est envoyé dans l'en-tête Authorization: Bearer <jeton>.

Basic

Saisissez l'« Utilisateur » (sans le caractère :) et le « Mot de passe ». Ils sont envoyés en authentification HTTP Basic.

OAuth 2.0

Avec OAuth 2.0, chaque personne qui utilise votre serveur depuis une IA se connecte avec son propre compte chez le fournisseur de votre API. Voozeo appelle alors votre API avec le jeton de cette personne, jamais avec un secret partagé. L'IA n'utilise pas de clé MCP : voir Serveurs en OAuth.

  1. Chez le fournisseur de votre API, créez une application OAuth (par exemple « OAuth apps » dans les réglages de développeur). Copiez-y telle quelle l'« URL de retour à déclarer chez le fournisseur » affichée dans l'onglet.
  2. De retour dans l'onglet « API cible », choisissez « OAuth 2.0 » et renseignez le « Client ID » et le « Client secret » fournis par le fournisseur.
  3. Renseignez l'« URL d'autorisation » et l'« URL du jeton » du fournisseur, en https://. L'URL d'autorisation ne doit pas contenir déjà les paramètres ajoutés par Voozeo (state, redirect_uri, client_id, response_type, code_challenge, code_challenge_method).
  4. Choisissez les « Scopes » à demander (50 au plus), la « Méthode d'authentification du client » (client_secret_basic, par défaut, ou client_secret_post quand le fournisseur attend le secret dans le corps de la requête, comme GitHub) et, si le fournisseur le demande, l'« Audience ».
  5. Cliquez sur « Enregistrer ».

Si votre OpenAPI déclare un schéma OAuth 2.0 avec le flux par code d'autorisation, les URL sont préremplies avec la mention « Détecté dans votre OpenAPI », et ses scopes sont proposés en cases à cocher, décochées. Vérifiez ces valeurs auprès de votre fournisseur : ce ne sont que des suggestions.

Le passage d'un serveur en OAuth 2.0 demande le client secret, et la clé MCP cesse aussitôt de fonctionner. Voozeo utilise toujours PKCE avec le fournisseur.

Transmis par l'appelant

Voozeo ne stocke aucun secret : pour chaque appel d'outil, il transmet à votre API l'en-tête reçu sur l'appel MCP, avec le même nom et la même valeur. Saisissez le « Nom de l'en-tête » (authorization par défaut). La valeur vient en général d'une passerelle OAuth placée devant Voozeo, pour que chaque utilisateur agisse avec ses propres droits : voir Identifiants par utilisateur avec une passerelle OAuth. Si l'en-tête est Authorization, seule l'URL qui contient la clé peut le transmettre. Le passage à ce type supprime un secret stocké ; en venant d'OAuth 2.0, il faut régénérer la clé MCP.

Secret en écriture seule

Le secret fait 4 096 caractères au plus. Il est stocké chiffré et ne s'affiche plus jamais après l'enregistrement : l'onglet indique seulement « Configuré ». Pour le changer, cliquez sur « Remplacer » et saisissez la nouvelle valeur. Si vous repassez à « Aucune », le secret enregistré est supprimé. L'IA ne voit jamais ce secret.

Avec OAuth 2.0, le secret est le client secret de votre application OAuth. Il n'est envoyé qu'à l'URL du jeton. Vous devez le saisir à nouveau quand vous passez en OAuth 2.0, ou quand vous changez le client ID ou l'URL du jeton.

Autorisations actives

Sur un serveur OAuth 2.0, l'onglet « API cible » affiche « Autorisations actives : n », le nombre de connexions d'IA en cours (« 1 000+ » au-delà).

  • « Révoquer toutes les autorisations » déconnecte toutes les IA après confirmation : chacune devra se reconnecter à son prochain appel.
  • Changer le type d'authentification, le client ID, l'URL d'autorisation ou l'URL du jeton révoque aussi toutes les autorisations ; l'onglet vous prévient avant l'enregistrement. Changer les scopes, l'audience, la méthode, le secret ou l'URL de base ne révoque rien.
  • Une personne peut aussi retirer l'accès depuis son compte chez le fournisseur de l'API (liste des applications OAuth autorisées).

Ce que reçoit l'IA

Avec OAuth 2.0, chaque appel part avec le jeton de la personne connectée depuis l'IA ; l'IA ne reçoit jamais ce jeton. La réponse de votre API est transmise à l'IA sous la forme HTTP <statut>, suivie du corps. Un corps JSON est remis en forme pour être lisible.

  • Au-delà de 100 KB, le texte est tronqué et la mention « [Truncated: the response exceeded 100 KB] » est ajoutée. Voozeo ne lit de toute façon que 1 Mio de réponse.
  • Un contenu binaire est résumé par [binary content: N bytes, type].
  • Un statut 400 ou plus est signalé comme une erreur d'outil (isError), le corps restant visible pour que l'IA comprenne.
  • Si la spec déclare un format de sortie que la réponse ne respecte pas, l'erreur est aussi signalée.

Erreurs d'appel

  • L'API ne répond pas en 10 secondes : l'IA reçoit un message « did not respond within 10 seconds ».
  • L'API est injoignable : message « could not be reached ».
  • L'adresse est interdite (réseau privé, par exemple) : l'appel est refusé.
  • Les redirections sont suivies jusqu'à 3 fois.

Chaque appel, réussi ou non, est visible dans le Journal des appels.

Exemple

Votre API attend une clé dans l'en-tête X-Api-Key. Vous saisissez l'URL de base https://api.example.com, choisissez « Clé d'API », nom X-Api-Key, emplacement « En-tête », collez le secret et cliquez sur « Enregistrer ». Le secret apparaît ensuite comme « Configuré ». Un appel à get_order renvoie par exemple :

HTTP 200

{
  "id": "A-1042",
  "status": "shipped"
}
Commencer