S'authentifier avec des coffres-forts

Les coffres-forts et les identifiants sont des primitives d'authentification qui vous permettent d'enregistrer des identifiants pour des services tiers une seule fois et de les référencer par ID lors de la création de session. Cela signifie que vous n'avez pas besoin de gérer votre propre magasin de secrets, de transmettre des jetons à chaque appel, ou de perdre la trace de l'utilisateur final au nom duquel un agent a agi.

La référence au coffre-fort est un paramètre par session, vous pouvez donc gérer votre produit au niveau de l'agent et vos utilisateurs au niveau de la session.

Créer un coffre-fort

Un coffre-fort est la collection de credentials associés à un utilisateur final. Donnez-lui un display_name et étiquetez-le optionnellement avec des metadata afin de pouvoir le relier à vos propres enregistrements d'utilisateurs.

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)

La réponse est l'enregistrement complet du coffre-fort :

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}

Ajouter un identifiant

Chaque identifiant est lié à une seule mcp_server_url. Lorsque l'agent se connecte à un serveur MCP lors de l'exécution de la session, l'API fait correspondre l'URL du serveur aux identifiants actifs sur le coffre-fort référencé et injecte le jeton.

Les identifiants sont stockés tels que fournis et ne sont pas validés avant l'exécution de la session. Un mauvais jeton se manifeste comme une erreur d'authentification MCP pendant la session, qui est émise mais ne bloque pas la poursuite de la session.

Contraintes :

• Un seul identifiant actif par mcp_server_url par coffre-fort. La création d'un second identifiant pour la même URL renvoie une erreur 409.
• mcp_server_url est immuable. Pour pointer vers un serveur différent, archivez cet identifiant et créez-en un nouveau.
• Maximum 20 identifiants par coffre-fort. Cela correspond au nombre maximum de serveurs MCP par agent.

Faire pivoter un identifiant

Seul le contenu secret et quelques champs de métadonnées sont modifiables. mcp_server_url, token_endpoint et client_id sont verrouillés après la création.

Référencer le coffre-fort lors de la création de session

Passez vault_ids lors de la création d'une session :

Comportement à l'exécution :

• Les identifiants sont résolus périodiquement pendant la session, de sorte qu'une rotation ou un archivage se propage aux sessions en cours sans redémarrage.
• Lorsqu'un coffre-fort n'a pas d'identifiant pour le serveur MCP, la connexion est tentée sans authentification et produit une erreur.
• Lorsque plusieurs coffres-forts couvrent le serveur MCP, le premier coffre-fort avec une correspondance l'emporte.

Autres opérations

• Lister les coffres-forts ou les identifiants : Paginé, du plus récent au plus ancien. Les enregistrements archivés sont exclus par défaut (passez include_archived=true pour les inclure).
• Archiver un coffre-fort : POST /v1/vaults/{id}/archive. Se propage en cascade à tous les identifiants. Les secrets sont purgés ; les enregistrements sont conservés à des fins d'audit. Les futures sessions référençant ce coffre-fort échouent ; les sessions en cours continuent.
• Archiver un identifiant : POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purge le contenu secret ; mcp_server_url reste visible. Libère la mcp_server_url pour un identifiant de remplacement.
• Supprimer un coffre-fort ou un identifiant : Suppression définitive. L'enregistrement n'est pas conservé. Utilisez l'archivage si vous avez besoin d'une piste d'audit.