Mit Vaults authentifizieren

Vaults und Credentials (Anmeldedaten) sind Authentifizierungsprimitive, mit denen du Anmeldedaten für Drittanbieterdienste einmal registrieren und sie bei der Session-Erstellung per ID referenzieren kannst. Das bedeutet, dass du keinen eigenen Secret-Store betreiben, nicht bei jedem Aufruf Token übertragen und nicht den Überblick darüber verlieren musst, im Namen welches Endbenutzers ein Agent gehandelt hat.

Die Vault-Referenz ist ein Parameter pro Session, sodass du dein Produkt auf der Granularität der agent-Ressource und deine Benutzer auf der Granularität der session-Ressource verwalten kannst.

Einen Vault erstellen

Ein Vault ist die Sammlung von credentials, die einem Endbenutzer zugeordnet sind. Gib ihm einen display_name und versieh ihn optional mit metadata, damit du ihn deinen eigenen Benutzerdatensätzen zuordnen kannst.

vault = client.beta.vaults.create(
    display_name="Alice",
    metadata={"external_user_id": "usr_abc123"},
)
print(vault.id)  # "vlt_01ABC..."

Die Antwort ist der vollständige Vault-Datensatz:

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

Ein Credential hinzufügen

Zwei Credential-Kategorien werden unterstützt:

• MCP-Credentials (mcp_oauth, static_bearer): Jedes Credential hat eine mcp_server_url als Schlüssel. Wenn sich der Agent zur Session-Laufzeit mit einem Server unter dieser URL verbindet, wird das Token automatisch eingefügt.
• Umgebungsvariablen (environment_variable): Jedes Credential hat einen secret_name (den Namen der Umgebungsvariable) als Schlüssel und wird in der Sandbox als undurchsichtiger Platzhalter gespeichert. Wenn der Agent eine ausgehende Anfrage initiiert, wird der undurchsichtige Platzhalter beim Egress durch das echte Secret ersetzt. Der Agent sieht den Secret-Wert nie. Verwende dies für jeden Dienst, der sich über eine Umgebungsvariable authentifiziert, etwa CLIs, SDKs oder direkte API-Aufrufe.

Die tatsächlichen Credential-Werte, die du angibst (token, access_token, refresh_token, client_secret, secret_value), werden als sensible, nur beschreibbare Felder behandelt und nie in API-Antworten zurückgegeben.

Um dasselbe Verhalten mit einer selbst gehosteten Sandbox zu erreichen, kannst du einen eigenen Proxy betreiben, der Platzhalterwerte beim Egress durch die echten Secrets ersetzt.

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

Credentials werden wie angegeben gespeichert und erst zur Session-Laufzeit validiert. Ein ungültiges Credential zeigt sich während der Session als Authentifizierungs- oder nachgelagerter Fehler, der ausgegeben wird, die Session aber nicht an der Fortsetzung hindert.

Einschränkungen:

• Eindeutiger Schlüssel pro Vault. mcp_server_url (MCP-Credentials) und secret_name (Umgebungsvariablen-Credentials) müssen unter den aktiven Credentials in einem Vault eindeutig sein. Das Erstellen eines Duplikats gibt einen 409 zurück.
• Schlüssel sind unveränderlich. Um mcp_server_url oder secret_name zu ändern, archiviere das Credential und erstelle ein neues.
• Maximal 20 Credentials pro Vault.

Den Vault bei der Session-Erstellung referenzieren

Übergib vault_ids beim Erstellen einer Session:

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

Laufzeitverhalten:

• Wenn kein MCP-Credential anhand der mcp_server_url übereinstimmt, wird die Verbindung ohne Authentifizierung versucht und schlägt fehl, wenn der Server eine Authentifizierung erfordert.
• Wenn mehrere Vaults ein passendes Credential enthalten, gewinnt der erste Vault mit einem Treffer.
• In Multiagent-Sessions gelten Vault-Credentials für jeden Thread. Ein Agent, dessen eigene Definition den passenden MCP-Server deklariert, authentifiziert sich mit diesen Credentials. Siehe Agenten mit MCP-Servern verbinden.

Ein Credential rotieren

Secret-Werte, display_name und (bei Umgebungsvariablen-Credentials) injection_location können aktualisiert werden. Aktualisierungen von injection_location werden pro Feld zusammengeführt, wie im Tab „Umgebungsvariable“ unter Ein Credential hinzufügen beschrieben. Bei einer laufenden Session wird eine Aktualisierung von injection_location auf dieselbe Weise übernommen wie eine Secret-Rotation: Die Credentials der Session werden ohne Neustart neu aufgelöst, wie unter Credential-Lebenszyklus beschrieben, und die aktualisierten Orte gelten für die nachfolgenden ausgehenden Anfragen der Session. Strukturelle Felder (mcp_server_url, secret_name, token_endpoint, client_id) sind nach der Erstellung gesperrt. Um sie zu ändern, archiviere das Credential und erstelle ein neues.

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-..."},
    },
)

Credential-Lebenszyklus

Credentials werden regelmäßig neu aufgelöst, sowohl während einer Session als auch während des Vault-Lebenszyklus. Dies stellt sicher, dass Rotation, Archivierung oder Löschung von Credentials ohne Neustart auf laufende Sessions propagiert wird.

Um benachrichtigt zu werden, wenn ein Credential archiviert oder gelöscht wird oder die Aktualisierung fehlschlägt, kannst du die Vault- und Credential-Webhooks abonnieren, die mit diesen Lebenszyklusänderungen verbunden sind.

Bei mcp_oauth-Credentials aktualisiert die Neuauflösung auch das Access-Token, falls es abgelaufen ist. Schlägt die Aktualisierung fehl, wird ein vault_credential.refresh_failed-Event ausgegeben.

Einen OAuth-Refresh-Fehler diagnostizieren

Um zu diagnostizieren, warum ein Refresh fehlgeschlagen ist, rufe POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate auf (oder client.beta.vaults.credentials.mcp_oauth_validate(...) im SDK). So kannst du entscheiden, wie du mit dem Fehler umgehst; die richtige Maßnahme hängt vom Fehlertyp ab.

Der status auf oberster Ebene sagt dir, was als Nächstes zu tun ist:

• valid: Das Token funktioniert; keine Maßnahme erforderlich.
• invalid: Der Grant ist weg oder der OAuth-Server hat den Refresh mit einem 4xx abgelehnt. Fordere den Endbenutzer auf, sich erneut zu autorisieren.
• unknown: Ein vorübergehender Fehler (5xx, 429 oder Netzwerkfehler). Warte und versuche es erneut.

validation = client.beta.vaults.credentials.mcp_oauth_validate(
    credential.id,
    vault_id=vault.id,
)
print(validation.status)  # "valid", "invalid", or "unknown"

Die Antwort ist ein vault_credential_validation-Objekt. mcp_probe enthält den fehlgeschlagenen Schritt des MCP-Handshakes; refresh enthält das Ergebnis des versuchten Refreshs.

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

Weitere Operationen

• Vaults oder Credentials auflisten: Paginiert, neueste zuerst. Archivierte Datensätze sind standardmäßig ausgeschlossen (übergib include_archived=true, um sie einzuschließen).
• Einen Vault archivieren: POST /v1/vaults/{id}/archive. Kaskadiert auf alle Credentials. Secrets werden gelöscht; Datensätze werden zu Prüfzwecken aufbewahrt. Zukünftige Sessions, die diesen Vault referenzieren, schlagen fehl; laufende Sessions werden fortgesetzt.
• Ein Credential archivieren: POST /v1/vaults/{id}/credentials/{cred_id}/archive. Löscht die Secret-Payload; der Credential-Schlüssel (mcp_server_url oder secret_name) bleibt sichtbar und wird für ein Ersatz-Credential freigegeben.
• Einen Vault oder ein Credential löschen: Endgültiges Löschen. Der Datensatz wird nicht aufbewahrt. Verwende die Archivierung, wenn du einen Audit-Trail benötigst.