Autenticazione con vault

I vault e le credenziali sono primitive di autenticazione che ti permettono di registrare le credenziali per servizi di terze parti una sola volta e farvi riferimento tramite ID al momento della creazione della sessione. Questo significa che non hai bisogno di gestire il tuo archivio di segreti, trasmettere token ad ogni chiamata, o perdere traccia di quale utente finale un agente ha agito per conto di.

Il riferimento al vault è un parametro per sessione, quindi puoi gestire il tuo prodotto a livello di agente e i tuoi utenti a livello di sessione.

Crea un vault

Un vault è la raccolta di credentials associate a un utente finale. Assegnagli un display_name e facoltativamente etichettalo con metadata in modo da poterlo mappare ai tuoi record utente.

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

La risposta è il record del vault completo:

{
  "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
}

Aggiungi una credenziale

Ogni credenziale si associa a un singolo mcp_server_url. Quando l'agente si connette a un server MCP durante l'esecuzione della sessione, l'API confronta l'URL del server con le credenziali attive sul vault referenziato e inietta il token.

Le credenziali vengono archiviate così come fornite e non vengono validate fino all'esecuzione della sessione. Un token non valido emerge come errore di autenticazione MCP durante la sessione, che viene emesso ma non blocca la continuazione della sessione.

Vincoli:

• Una credenziale attiva per mcp_server_url per vault. La creazione di una seconda credenziale per lo stesso URL restituisce un 409.
• mcp_server_url è immutabile. Per puntare a un server diverso, archivia questa credenziale e creane una nuova.
• Massimo 20 credenziali per vault. Questo corrisponde alla quantità massima di server MCP per agente.

Ruota una credenziale

Solo il payload segreto e alcuni campi di metadati sono mutabili. mcp_server_url, token_endpoint e client_id sono bloccati dopo la creazione.

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

Fai riferimento al vault al momento della creazione della sessione

Passa vault_ids quando crei una sessione:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
    title="Alice's Slack digest",
)

Comportamento a runtime:

• Le credenziali vengono risolte periodicamente durante la sessione, quindi una rotazione o un archivio si propaga alle sessioni in esecuzione senza un riavvio.
• Quando un vault non ha credenziali per il server MCP, il tentativo di connessione viene effettuato senza autenticazione e produce un errore.
• Quando più vault coprono il server MCP, il primo vault con una corrispondenza vince.

Altre operazioni

• Elenca vault o credenziali: Paginato, più recente per primo. I record archiviati sono esclusi per impostazione predefinita (passa include_archived=true per includerli).
• Archivia un vault: POST /v1/vaults/{id}/archive. Si propaga a tutte le credenziali. I segreti vengono eliminati; i record vengono conservati per il controllo. Le sessioni future che fanno riferimento a questo vault non riescono; le sessioni in esecuzione continuano.
• Archivia una credenziale: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Elimina il payload segreto; mcp_server_url rimane visibile. Libera mcp_server_url per una credenziale sostitutiva.
• Elimina un vault o una credenziale: Eliminazione permanente. Il record non viene conservato. Usa l'archivio se hai bisogno di un audit trail.