S'authentifier avec des coffres-forts

Les coffres-forts (vaults) et les identifiants (credentials) sont des primitives d'authentification qui vous permettent d'enregistrer une seule fois des identifiants pour des services tiers et de les référencer par ID lors de la création d'une session. Cela signifie que vous n'avez pas besoin de gérer votre propre magasin de secrets, de transmettre des jetons à chaque appel, ni 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, ce qui vous permet de gérer votre produit à la granularité de la ressource agent et vos utilisateurs à la granularité de la ressource session.



Créer un coffre-fort

Un coffre-fort est la collection de credentials associée à un utilisateur final. Attribuez-lui un display_name et, éventuellement, étiquetez-le avec des metadata afin de pouvoir le faire correspondre à vos propres enregistrements d'utilisateurs.

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

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

Deux catégories d'identifiants sont prises en charge :

• Identifiants MCP (mcp_oauth, static_bearer) : chaque identifiant est indexé par une mcp_server_url. Lorsque l'agent se connecte à un serveur à cette URL pendant l'exécution de la session, le jeton est injecté automatiquement.
• Variables d'environnement (environment_variable) : chaque identifiant est indexé par un secret_name (le nom de la variable d'environnement) et stocké dans le bac à sable sous forme d'espace réservé opaque. Lorsque l'agent initie une requête sortante, l'espace réservé opaque est remplacé par le secret réel à la sortie. L'agent ne voit jamais la valeur du secret. Utilisez ce type pour tout service qui s'authentifie via une variable d'environnement, comme les CLI, les SDK ou les appels API directs.

Les valeurs d'identifiants réelles que vous fournissez (token, access_token, refresh_token, client_secret, secret_value) sont traitées comme des champs sensibles en écriture seule et ne sont jamais renvoyées dans les réponses de l'API.

Les identifiants sont stockés tels que fournis et ne sont pas validés avant l'exécution de la session. Un identifiant invalide se manifeste sous la forme d'une erreur d'authentification ou d'une erreur en aval pendant la session, qui est émise mais n'empêche pas la session de se poursuivre.

Contraintes :

• Clé unique par coffre-fort. mcp_server_url (identifiants MCP) et secret_name (identifiants de type variable d'environnement) doivent être uniques parmi les identifiants actifs d'un coffre-fort. La création d'un doublon renvoie une erreur 409.
• Les clés sont immuables. Pour modifier mcp_server_url ou secret_name, archivez l'identifiant et créez-en un nouveau.
• Maximum de 20 identifiants par coffre-fort.



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

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

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

Comportement à l'exécution :

• Lorsqu'aucun identifiant MCP ne correspond par mcp_server_url, la connexion est tentée sans authentification et générera une erreur si le serveur exige une authentification.
• Lorsque plusieurs coffres-forts contiennent un identifiant correspondant, le premier coffre-fort avec une correspondance l'emporte.
• Dans les sessions multi-agents, les identifiants du coffre-fort s'appliquent à chaque thread. Un agent dont la propre définition déclare le serveur MCP correspondant s'authentifie avec ces identifiants. Consultez Connecter des agents à des serveurs MCP.



Effectuer la rotation d'un identifiant

Les valeurs de secret, display_name et (sur les identifiants de type variable d'environnement) injection_location peuvent être mis à jour. Les mises à jour de injection_location fusionnent champ par champ, comme décrit dans l'onglet Variable d'environnement de la section Ajouter un identifiant. Pour une session en cours d'exécution, une mise à jour de injection_location se propage de la même manière qu'une rotation de secret : les identifiants de la session sont résolus à nouveau sans redémarrage, comme décrit dans Cycle de vie des identifiants, et les emplacements mis à jour s'appliquent aux requêtes sortantes ultérieures de la session. Les champs structurels (mcp_server_url, secret_name, token_endpoint, client_id) sont verrouillés après la création. Pour les modifier, archivez l'identifiant et créez-en un nouveau.

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'YAML'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
YAML



Cycle de vie des identifiants

Les identifiants sont résolus à nouveau périodiquement, à la fois pendant une session et pendant le cycle de vie du coffre-fort. Cela garantit que la rotation, l'archivage ou la suppression d'un identifiant se propage aux sessions en cours d'exécution sans redémarrage.

Pour être notifié si un identifiant est archivé, supprimé ou échoue à s'actualiser, vous pouvez vous abonner aux webhooks de coffre-fort et d'identifiant associés à ces changements de cycle de vie.

Pour les identifiants mcp_oauth, la nouvelle résolution actualise également le jeton d'accès s'il a expiré. Si l'actualisation échoue, un événement vault_credential.refresh_failed est émis.



Diagnostiquer un échec d'actualisation OAuth

Pour diagnostiquer la raison de l'échec d'une actualisation, appelez POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (ou client.beta.vaults.credentials.mcp_oauth_validate(...) dans le SDK). Cela vous permet de décider comment gérer l'échec ; l'action appropriée dépend du type d'erreur.

Le status de niveau supérieur vous indique la marche à suivre :

• valid : le jeton fonctionne ; aucune action requise.
• invalid : l'autorisation a disparu ou le serveur OAuth a rejeté l'actualisation avec une erreur 4xx. Invitez l'utilisateur final à autoriser à nouveau.
• unknown : une erreur transitoire (5xx, 429 ou défaillance réseau). Attendez et réessayez.

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

La réponse est un objet vault_credential_validation. mcp_probe inclut l'étape de la négociation MCP qui a échoué ; refresh inclut le résultat de la tentative d'actualisation.

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



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 d'exécution continuent.
• Archiver un identifiant : POST /v1/vaults/{id}/credentials/{cred_id}/archive. Purge la charge utile du secret ; la clé de l'identifiant (mcp_server_url ou secret_name) reste visible et est libérée 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.