Autenticazione con i vault

I vault e le credenziali sono primitive di autenticazione che ti permettono 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 un agente abbia rappresentato.

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.



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 ricondurre 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
}



Aggiungi 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 uscita (egress). L'agente non vede mai il valore del segreto. Usa questa categoria 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.

CREDENTIAL_ID=$(ant beta:vaults:credentials create \
  --vault-id "$VAULT_ID" \
  --display-name "Alice's Slack" \
  --transform id --raw-output <<'YAML'
auth:
  type: mcp_oauth
  mcp_server_url: https://mcp.slack.com/mcp
  access_token: xoxp-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    token_endpoint: https://slack.com/api/oauth.v2.access
    client_id: "1234567890.0987654321"
    scope: channels:read chat:write
    refresh_token: xoxe-1-...
    token_endpoint_auth:
      type: client_secret_post
      client_secret: abc123...
YAML
)

Le credenziali vengono memorizzate così come fornite e non vengono convalidate fino all'esecuzione della sessione. Una credenziale non valida si manifesta come un errore di autenticazione o a valle 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 basate su variabili d'ambiente) devono essere univoci tra le credenziali attive in un vault. La creazione di un duplicato restituisce un 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.



Referenzia il vault alla creazione della sessione

Passa vault_ids durante la creazione di 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 multiagente, 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 Connetti gli agenti ai server MCP.



Ruota una credenziale

I valori dei segreti, display_name e (sulle credenziali basate su variabili d'ambiente) injection_location possono essere aggiornati. Gli aggiornamenti di injection_location vengono uniti campo per campo, come descritto nella scheda Variabile d'ambiente di Aggiungi 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 ri-risolte senza un 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 ri-risolte 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 un riavvio.

Per essere avvisato se una credenziale viene archiviata, eliminata o non riesce ad aggiornarsi, puoi sottoscrivere i webhook di vault e credenziali associati a tali cambiamenti del ciclo di vita.

Per le credenziali mcp_oauth, la ri-risoluzione aggiorna anche il token di accesso se è scaduto. Se il refresh fallisce, viene emesso un evento vault_credential.refresh_failed.



Diagnostica 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 (oppure client.beta.vaults.credentials.mcp_oauth_validate(...) nell'SDK). Questo ti permette di decidere come gestire l'errore; l'azione corretta dipende dal tipo di errore.

Lo status di primo livello ti indica cosa fare successivamente:

• valid: il token funziona; nessuna azione necessaria.
• invalid: il grant non esiste più oppure il server OAuth ha rifiutato il refresh con un 4xx. Chiedi all'utente finale di ri-autorizzare.
• 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 dell'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

• Elenca vault o credenziali: Paginato, dal più recente. 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 l'auditing. Le sessioni future che referenziano questo vault falliscono; le sessioni in esecuzione continuano.
• Archivia 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.
• Elimina un vault o una credenziale: Eliminazione definitiva. Il record non viene conservato. Usa l'archiviazione se hai bisogno di una traccia di audit.