Connexions · Documentation Ephemeral

Enregistrez des connexions HTTP et MCP, autorisez des connexions OAuth et listez ce que les exécutions peuvent utiliser. Configurer des connexions exige une clé admin ou un propriétaire ou administrateur connecté ; les membres peuvent lire le catalogue. Voir connexions pour la façon dont les appels sont relayés.

Enregistrer une connexion

PUT/v1/connections/{name}

Crée la connexion, ou la remplace si le nom existe. Les noms suivent les mêmes règles que les noms de workflows. Propriétaire ou administrateur uniquement.

Corps

typestringobligatoire

http ou mcp.

urlstringobligatoire

URL de base HTTPS de l'API, ou endpoint Streamable HTTP du serveur MCP. Doit pointer vers une adresse publique.

authobject

Comment s'authentifier. À omettre pour aucune authentification.

allowed_methodsstring[]

Connexions HTTP : méthodes que les exécutions peuvent utiliser, par exemple ["GET"]. Vide autorise tout.

allowed_toolsstring[]

Connexions MCP : noms des outils que les exécutions peuvent appeler. Vide autorise tout.

instructionsstring

Comment l'agent doit utiliser l'API : endpoints, formats de requête, conventions. Montré à l'agent, donc sans secrets. 4 000 caractères au maximum.

L'objet auth

typestring

none, bearer, header, basic ou oauth2.

tokenstring

Pour bearer et header.

headerstring

Pour header : le nom de l'en-tête, par exemple X-API-Key.

username, passwordstring

Pour basic. Le nom d'utilisateur ne peut pas contenir de deux-points.

client_idstring

Pour oauth2. Obligatoire, avec authorization_url et token_url.

client_secretstring

Pour les clients oauth2 qui en ont un.

authorization_url, token_urlstring

Les endpoints OAuth du fournisseur. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post ou none.

scopesstring[]

Scopes à demander.

resourcestring

Indicateur de ressource facultatif, envoyé avec la demande d'autorisation.

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

La réponse est {"name": "...", "type": "..."}. Ephemeral valide l'URL et le format des identifiants avant d'enregistrer.

Pour mettre à jour une connexion sans renvoyer ses secrets, enregistrez-la en omettant les champs secrets et avec le même auth.type. Le jeton, le mot de passe, le secret client et les jetons OAuth stockés sont conservés. Changer auth.type remplace entièrement l'authentification.

Lister les connexions

GET/v1/connections

Propriétaire ou administrateur uniquement. Renvoie chaque connexion avec name, type, url, allowed_methods, allowed_tools, authenticated et les parties non secrètes de auth.

Lire une connexion

GET/v1/connections/{name}

Propriétaire ou administrateur uniquement. Renvoie la configuration sans les identifiants et avec les valeurs de requête des URL masquées.

Supprimer une connexion

DELETE/v1/connections/{name}

Propriétaire ou administrateur uniquement. Renvoie 204 No Content.

Une exécution qui référence une connexion supprimée, directement ou via un workflow, est rejetée à sa création. Une exécution déjà en cours perd l'accès la prochaine fois qu'elle appelle la connexion.

Autoriser une connexion OAuth

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

Propriétaire ou administrateur uniquement. Renvoie {"url": "..."}, la page d'autorisation du fournisseur.

Ouvrez l'URL dans un navigateur et approuvez l'accès. Le fournisseur redirige vers /oauth/callback sur le moteur, Ephemeral échange le code et stocke les jetons, puis le navigateur revient au tableau de bord. Chaque URL ne fonctionne qu'une fois. Enregistrez https://app.ephemer.al/oauth/callback comme URI de redirection auprès de votre fournisseur, ou votre propre domaine sur une installation auto-hébergée.

Si l'ID client ou les endpoints OAuth de la connexion changent pendant l'autorisation, le callback est refusé avec 409 ; recommencez. La CLI fait tout cela en une étape avec ephemeral oauth connect NAME.

Catalogue des connexions

GET/v1/catalog/connections

Accessible à tous les rôles. Liste les connexions que les exécutions peuvent référencer, sans les URL ni les paramètres d'authentification.

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 }
]

L'accès aux connexions enregistrées s'applique à toute l'organisation. Chaque membre peut utiliser chaque connexion enregistrée par son nom ; il n'existe pas d'autorisations par membre.