Autenticazione con i vault

I vault e le credenziali sono primitive di autenticazione che ti consentono di registrare una sola volta le credenziali per servizi di terze parti e di referenziarle tramite ID al momento della creazione della sessione. Questo significa che non devi gestire un tuo archivio di segreti, trasmettere token a ogni chiamata o perdere traccia di quale utente finale l'agente stava rappresentando.

Il riferimento al vault è un parametro per sessione, quindi puoi gestire il tuo prodotto alla granularità della risorsa agent e i tuoi utenti alla granularità della risorsa session.



Creare un vault

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

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 risposta è il record completo del vault:

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



Aggiungere una credenziale

Sono supportate due categorie di credenziali:

• Credenziali MCP (mcp_oauth, static_bearer): ogni credenziale è identificata da un mcp_server_url. Quando l'agente si connette a un server a quell'URL durante l'esecuzione della sessione, il token viene iniettato automaticamente.
• Variabili d'ambiente (environment_variable): ogni credenziale è identificata da un secret_name (il nome della variabile d'ambiente) e memorizzata nella sandbox come segnaposto opaco. Quando l'agente avvia una richiesta in uscita, il segnaposto opaco viene sostituito con il segreto reale in fase di egress. L'agente non vede mai il valore del segreto. Usa questa opzione per qualsiasi servizio che si autentica tramite una variabile d'ambiente, come CLI, SDK o chiamate API dirette.

I valori effettivi delle credenziali che fornisci (token, access_token, refresh_token, client_secret, secret_value) sono trattati come campi sensibili di sola scrittura e non vengono mai restituiti nelle risposte dell'API.

Le credenziali vengono memorizzate così come fornite e non vengono convalidate fino all'esecuzione della sessione. Una credenziale non valida si manifesta come errore di autenticazione o errore downstream durante la sessione, che viene emesso ma non impedisce alla sessione di continuare.

Vincoli:

• Chiave univoca per vault. mcp_server_url (credenziali MCP) e secret_name (credenziali di tipo variabile d'ambiente) devono essere univoci tra le credenziali attive in un vault. La creazione di un duplicato restituisce un errore 409.
• Le chiavi sono immutabili. Per modificare mcp_server_url o secret_name, archivia la credenziale e creane una nuova.
• Massimo 20 credenziali per vault.



Referenziare il vault alla creazione della sessione

Passa vault_ids quando crei una sessione:

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)

Comportamento a runtime:

• Quando nessuna credenziale MCP corrisponde per mcp_server_url, la connessione viene tentata senza autenticazione e genererà un errore se il server richiede l'autenticazione.
• Quando più vault contengono una credenziale corrispondente, vince il primo vault con una corrispondenza.
• Nelle sessioni multi-agente, le credenziali del vault si applicano a ogni thread. Un agente la cui definizione dichiara il server MCP corrispondente si autentica con queste credenziali. Consulta Connettere gli agenti ai server MCP.



Ruotare una credenziale

I valori dei segreti, display_name e (sulle credenziali di tipo variabile d'ambiente) injection_location possono essere aggiornati. Gli aggiornamenti di injection_location vengono uniti per campo, come descritto nella scheda Variabile d'ambiente di Aggiungere una credenziale. Per una sessione in esecuzione, un aggiornamento di injection_location si propaga allo stesso modo di una rotazione del segreto: le credenziali della sessione vengono risolte nuovamente senza riavvio, come descritto in Ciclo di vita delle credenziali, e le posizioni aggiornate si applicano alle successive richieste in uscita della sessione. I campi strutturali (mcp_server_url, secret_name, token_endpoint, client_id) sono bloccati dopo la creazione. Per modificarli, archivia la credenziale e creane una nuova.

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



Ciclo di vita delle credenziali

Le credenziali vengono risolte nuovamente periodicamente, sia durante una sessione sia durante il ciclo di vita del vault. Questo garantisce che la rotazione, l'archiviazione o l'eliminazione delle credenziali si propaghi alle sessioni in esecuzione senza riavvio.

Per ricevere una notifica se una credenziale viene archiviata, eliminata o non riesce ad aggiornarsi, puoi iscriverti ai webhook di vault e credenziali associati a tali cambiamenti del ciclo di vita.

Per le credenziali mcp_oauth, la nuova risoluzione aggiorna anche l'access token se è scaduto. Se il refresh fallisce, viene emesso un evento vault_credential.refresh_failed.



Diagnosticare un errore di refresh OAuth

Per diagnosticare il motivo per cui un refresh è fallito, chiama POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (o client.beta.vaults.credentials.mcp_oauth_validate(...) nell'SDK). Questo ti consente di decidere come gestire l'errore; l'azione corretta dipende dal tipo di errore.

Il campo status di primo livello ti indica cosa fare dopo:

• valid: il token funziona; nessuna azione necessaria.
• invalid: il grant non esiste più o il server OAuth ha rifiutato il refresh con un errore 4xx. Chiedi all'utente finale di autorizzare nuovamente.
• unknown: un errore transitorio (5xx, 429 o errore di rete). Attendi e riprova.

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

La risposta è un oggetto vault_credential_validation. mcp_probe include il passaggio di handshake MCP fallito; refresh include l'esito del tentativo di refresh.

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



Altre operazioni

• Elencare vault o credenziali: Paginato, dal più recente al meno recente. I record archiviati sono esclusi per impostazione predefinita (passa include_archived=true per includerli).
• Archiviare un vault: POST /v1/vaults/{id}/archive. Si propaga a cascata a tutte le credenziali. I segreti vengono eliminati; i record vengono conservati per scopi di audit. Le sessioni future che referenziano questo vault falliscono; le sessioni in esecuzione continuano.
• Archiviare una credenziale: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Elimina il payload del segreto; la chiave della credenziale (mcp_server_url o secret_name) rimane visibile e viene liberata per una credenziale sostitutiva.
• Eliminare un vault o una credenziale: Eliminazione definitiva. Il record non viene conservato. Usa l'archiviazione se hai bisogno di una traccia di audit.