Verbindungen · Ephemeral Docs

Speichern Sie HTTP- und MCP-Verbindungen, autorisieren Sie OAuth-Verbindungen und listen Sie auf, was Ausführungen nutzen können. Zum Konfigurieren von Verbindungen ist ein Admin-Schlüssel oder ein angemeldeter Inhaber oder Admin nötig; Mitglieder können den Katalog lesen. Wie Aufrufe vermittelt werden, beschreibt Verbindungen.

Eine Verbindung speichern

PUT/v1/connections/{name}

Erstellt die Verbindung oder ersetzt sie, falls der Name existiert. Für Namen gelten dieselben Regeln wie für Workflow-Namen. Nur Inhaber oder Admin.

Body

typestringerforderlich

http oder mcp.

urlstringerforderlich

HTTPS-Basis-URL der API oder Streamable-HTTP-Endpunkt des MCP-Servers. Muss auf eine öffentliche Adresse auflösen.

authobject

Wie authentifiziert wird. Weglassen für keine.

allowed_methodsstring[]

HTTP-Verbindungen: Methoden, die Ausführungen verwenden dürfen, etwa ["GET"]. Leer erlaubt alle.

allowed_toolsstring[]

MCP-Verbindungen: Tool-Namen, die Ausführungen aufrufen dürfen. Leer erlaubt alle.

instructionsstring

Wie der Agent die API nutzen soll: Endpunkte, Anfrageformate, Konventionen. Wird dem Agenten angezeigt, enthalten Sie also keine Geheimnisse. Bis zu 4.000 Zeichen.

Das auth-Objekt

typestring

none, bearer, header, basic oder oauth2.

tokenstring

Für bearer und header.

headerstring

Für header: der Header-Name, etwa X-API-Key.

username, passwordstring

Für basic. Der Benutzername darf keinen Doppelpunkt enthalten.

client_idstring

Für oauth2. Erforderlich, zusammen mit authorization_url und token_url.

client_secretstring

Für oauth2-Clients, die eines haben.

authorization_url, token_urlstring

Die OAuth-Endpunkte des Anbieters. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post oder none.

scopesstring[]

Anzufordernde Scopes.

resourcestring

Optionaler Ressourcenindikator, der mit der Autorisierungsanfrage gesendet wird.

{
  "type": "http",
  "url": "https://api.example.com/v2",
  "auth": { "type": "header", "header": "X-API-Key", "token": "sk_live_…" },
  "allowed_methods": ["GET"],
  "instructions": "Look up a payment with GET /v1/payments/{id}. Amounts are in cents."
}

Die Antwort lautet {"name": "...", "type": "..."}. Ephemeral validiert die URL und das Format der Zugangsdaten vor dem Speichern.

Um eine Verbindung zu aktualisieren, ohne ihre Geheimnisse erneut zu senden, speichern Sie sie ohne die Geheimnisfelder und mit demselben auth.type. Das gespeicherte Token, Passwort, Client-Secret und die OAuth-Tokens bleiben erhalten. Eine Änderung von auth.type ersetzt die Authentifizierung vollständig.

Verbindungen auflisten

GET/v1/connections

Nur Inhaber oder Admin. Liefert jede Verbindung mit name, type, url, allowed_methods, allowed_tools, authenticated und den nicht geheimen Teilen von auth.

Eine Verbindung abrufen

GET/v1/connections/{name}

Nur Inhaber oder Admin. Liefert die Konfiguration ohne Zugangsdaten und mit maskierten Query-Werten in URLs.

Eine Verbindung löschen

DELETE/v1/connections/{name}

Nur Inhaber oder Admin. Liefert 204 No Content.

Eine Ausführung, die eine gelöschte Verbindung direkt oder über einen Workflow referenziert, wird beim Erstellen abgelehnt. Eine bereits laufende Ausführung verliert den Zugriff, sobald sie die Verbindung das nächste Mal aufruft.

Eine OAuth-Verbindung autorisieren

POST/v1/connections/{name}/oauth/start

Nur Inhaber oder Admin. Liefert {"url": "..."}, die Autorisierungsseite des Anbieters.

Öffnen Sie die URL in einem Browser und bestätigen Sie den Zugriff. Der Anbieter leitet auf /oauth/callback der Engine weiter, Ephemeral tauscht den Code ein und speichert die Tokens, und der Browser kehrt zum Dashboard zurück. Jede URL funktioniert einmal. Registrieren Sie https://app.ephemer.al/oauth/callback als Redirect-URI bei Ihrem Anbieter, bei einer selbst gehosteten Installation Ihre eigene Domain.

Ändern sich die Client-ID oder die OAuth-Endpunkte der Verbindung, während die Autorisierung läuft, wird der Callback mit 409 abgelehnt; starten Sie erneut. Die CLI erledigt dies in einem Schritt mit ephemeral oauth connect NAME.

Verbindungskatalog

GET/v1/catalog/connections

Für jede Rolle verfügbar. Listet die Verbindungen auf, die Ausführungen referenzieren können, ohne URLs oder Authentifizierungseinstellungen.

JSON

[
  { "name": "docs-mcp", "type": "mcp", "allowed_methods": [], "allowed_tools": ["search", "get_document"], "authenticated": true },
  { "name": "payments-api", "type": "http", "allowed_methods": ["GET"], "allowed_tools": null, "authenticated": true }
]

Der Zugriff auf gespeicherte Verbindungen gilt organisationsweit. Jedes Mitglied kann jede gespeicherte Verbindung per Name nutzen; es gibt keine Freigaben pro Mitglied.