Mit Vaults authentifizieren

Vaults und Credentials sind Authentifizierungs-Primitive, mit denen du Anmeldedaten für Drittanbieterdienste einmalig registrieren und bei der Session-Erstellung per ID referenzieren kannst. Das bedeutet, du musst keinen eigenen Secret-Store betreiben, keine Tokens bei jedem Aufruf übertragen und verlierst nicht den Überblick darüber, im Namen welches Endbenutzers ein Agent gehandelt hat.

Die Vault-Referenz ist ein sessionspezifischer Parameter, sodass du dein Produkt auf der Granularitätsebene der agent-Ressource und deine Benutzer auf der Granularitätsebene 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 versehe 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 der Agent zur Session-Laufzeit eine Verbindung zu einem Server unter dieser URL herstellt, 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, schreibgeschützte Felder behandelt und nie in API-Antworten zurückgegeben.

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

Einschränkungen:

• Eindeutiger Key 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.
• Keys 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 per 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 Multi-Agent-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. Bei einer laufenden Session wird ein injection_location-Update auf die gleiche Weise propagiert wie eine Secret-Rotation: Die Credentials der Session werden ohne Neustart neu aufgelöst, wie unter Credential-Lebenszyklus beschrieben, und die aktualisierten Locations 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 ein Refresh 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 der Refresh fehlschlägt, 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 Aktion hängt vom Fehlertyp ab.

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

• valid: Das Token funktioniert; keine Aktion 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.

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 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 für Audit-Zwecke 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-Key (mcp_server_url oder secret_name) bleibt sichtbar und wird für ein Ersatz-Credential freigegeben.
• Einen Vault oder ein Credential löschen: Hard Delete. Der Datensatz wird nicht aufbewahrt. Verwende die Archivierung, wenn du einen Audit-Trail benötigst.