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 farvi riferimento tramite ID al momento della creazione della sessione. Ciò 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 con la granularità della risorsa agent e i tuoi utenti con la 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 ricollegare ai tuoi record utente.

vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(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 fase di egress (uscita). 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.

credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Alice's Slack",
    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.user.access",
            "client_id": "1234567890.0987654321",
            "scope": "channels:read chat:write",
            "refresh_token": "xoxe-1-...",
            "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "abc123..."},
        },
    },
)

bearer_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Linear API key",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://mcp.linear.app/mcp",
        "token": "lin_api_your_linear_key",
    },
)

env_credential = client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Notion API key for sandbox",
    auth={
        "type": "environment_variable",
        "secret_name": "NOTION_API_KEY",
        "secret_value": "ntn_your-secret-here",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.notion.com"],
        },
        "injection_location": {"header": True},
    },
)
if env_credential.auth.type == "environment_variable":
    location = env_credential.auth.injection_location
    print(f"header: {location.header}, body: {location.body}")  # header: True, body: False

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 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 di tipo variabile 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.

Fai riferimento al vault alla 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 in fase di esecuzione:

• 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, prevale 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 Connettere gli agenti ai server MCP.

Ruota 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 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 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.

client.beta.vaults.credentials.update(
    credential.id,
    vault_id=vault.id,
    auth={
        "type": "mcp_oauth",
        "access_token": "xoxp-new-...",
        "expires_at": "2099-12-31T23:59:59Z",
        "refresh": {"refresh_token": "xoxe-1-new-..."},
    },
)

Ciclo di vita delle credenziali

Le credenziali vengono risolte nuovamente a intervalli periodici, sia durante una sessione sia durante il ciclo di vita del vault. Ciò 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 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 non è riuscito, chiama POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate (oppure client.beta.vaults.credentials.mcp_oauth_validate(...) nell'SDK). In questo modo puoi 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 autorizzare nuovamente.
• unknown: un errore transitorio (5xx, 429 o errore di rete). Attendi e riprova.

validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "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

• Elencare vault o credenziali: Paginato, dal più 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 definitivamente; i record vengono conservati a fini di audit. Le sessioni future che fanno riferimento a questo vault falliscono; le sessioni in esecuzione continuano.
• Archiviare una credenziale: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Elimina definitivamente 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.