Authentifizierung mit Vaults

„Vaults" (Tresore) und „credentials" (Anmeldedaten) sind Authentifizierungs-Primitive, mit denen du Anmeldedaten für Drittanbieterdienste einmal registrieren und bei der Session-Erstellung per ID referenzieren kannst. Das bedeutet, dass du keinen eigenen Secret-Store betreiben, keine Tokens bei jedem Aufruf übertragen und nicht den Überblick darüber verlieren musst, in wessen Namen 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_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)
echo "$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 wird über eine mcp_server_url identifiziert. Wenn sich der Agent zur Session-Laufzeit mit einem Server unter dieser URL verbindet, wird das Token automatisch injiziert.
• Umgebungsvariablen (environment_variable): Jedes Credential wird über einen secret_name (den Namen der Umgebungsvariable) identifiziert und in der Sandbox als opaker Platzhalter gespeichert. Wenn der Agent eine ausgehende Anfrage initiiert, wird der opake 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, wie 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 schreibbare Felder behandelt und niemals in API-Antworten zurückgegeben.

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
)

Credentials werden so gespeichert, wie sie bereitgestellt wurden, und erst zur Session-Laufzeit validiert. Ein ungültiges Credential zeigt sich als Authentifizierungs- oder Downstream-Fehler während der Session, der ausgegeben wird, aber die Fortsetzung der Session nicht blockiert.

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_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)

Laufzeitverhalten:

• Wenn kein MCP-Credential über mcp_server_url übereinstimmt, wird die Verbindung unauthentifiziert versucht und schlägt fehl, wenn der Server eine Authentifizierung erfordert.
• Wenn mehrere Vaults ein passendes Credential enthalten, gewinnt der erste Vault mit einer Übereinstimmung.
• 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 Agents mit MCP-Servern verbinden.



Ein Credential rotieren

Secret-Werte, display_name und (bei Umgebungsvariablen-Credentials) injection_location können aktualisiert werden. injection_location-Updates werden pro Feld zusammengeführt, wie im Tab „Umgebungsvariable" unter Ein Credential hinzufügen beschrieben. Für eine laufende Session wird ein injection_location-Update auf dieselbe Weise propagiert wie eine Secret-Rotation: Die Credentials der Session werden ohne Neustart neu aufgelöst, wie in 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.

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



Credential-Lebenszyklus

Credentials werden periodisch neu aufgelöst, sowohl während einer Session als auch während des Vault-Lebenszyklus. Dies stellt sicher, dass Credential-Rotation, -Archivierung oder -Löschung ohne Neustart an 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, wenn es abgelaufen ist. Wenn die Aktualisierung fehlschlägt, wird ein vault_credential.refresh_failed-Event ausgegeben.



Einen OAuth-Refresh-Fehler diagnostizieren

Um zu diagnostizieren, warum eine Aktualisierung 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 nicht mehr vorhanden oder der OAuth-Server hat die Aktualisierung 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.

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

Die Antwort ist ein vault_credential_validation-Objekt. mcp_probe enthält den fehlgeschlagenen MCP-Handshake-Schritt; refresh enthält das Ergebnis des versuchten 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
  }
}



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 Audit-Zwecken 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.