Connections · Ephemeral docs

Save HTTP and MCP connections, authorize OAuth connections and list what runs can use. Configuring connections needs an admin key or a signed-in owner or admin; members can read the catalog. See connections for how calls are brokered.

Save a connection

PUT/v1/connections/{name}

Creates the connection, or replaces it if the name exists. Names follow the same rules as workflow names. Owner or admin only.

Body

typestringrequired

http or mcp.

urlstringrequired

HTTPS base URL of the API, or the MCP server's Streamable HTTP endpoint. Must resolve to a public address.

authobject

How to authenticate. Omit for none.

allowed_methodsstring[]

HTTP connections: methods runs may use, such as ["GET"]. Empty allows all.

allowed_toolsstring[]

MCP connections: tool names runs may call. Empty allows all.

instructionsstring

How the agent should use the API: endpoints, request formats, conventions. Shown to the agent, so keep secrets out. Up to 4,000 characters.

The auth object

typestring

none, bearer, header, basic or oauth2.

tokenstring

For bearer and header.

headerstring

For header: the header name, such as X-API-Key.

username, passwordstring

For basic. The username cannot contain a colon.

client_idstring

For oauth2. Required, with authorization_url and token_url.

client_secretstring

For oauth2 clients that have one.

authorization_url, token_urlstring

The provider's OAuth endpoints. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post or none.

scopesstring[]

Scopes to request.

resourcestring

Optional resource indicator sent with the authorization request.

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

The response is {"name": "...", "type": "..."}. Ephemeral validates the URL and credentials format before saving.

To update a connection without resending its secrets, save it with the secret fields left out and the same auth.type. The stored token, password, client secret and OAuth tokens are kept. Changing auth.type replaces the authentication entirely.

List connections

GET/v1/connections

Owner or admin only. Returns every connection with name, type, url, allowed_methods, allowed_tools, authenticated and the non-secret parts of auth.

Get a connection

GET/v1/connections/{name}

Owner or admin only. Returns the configuration with credentials removed and query values in URLs masked.

Delete a connection

DELETE/v1/connections/{name}

Owner or admin only. Returns 204 No Content.

A run that references a deleted connection, directly or through a workflow, is rejected when you create it. A run already in progress loses access the next time it calls the connection.

Authorize an OAuth connection

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

Owner or admin only. Returns {"url": "..."}, the provider's authorization page.

Open the URL in a browser and approve access. The provider redirects to /oauth/callback on the engine, Ephemeral exchanges the code and stores the tokens, and the browser returns to the dashboard. Each URL works once. Register https://app.ephemer.al/oauth/callback as the redirect URI with your provider, or your own domain on a self-hosted installation.

If the connection's client ID or OAuth endpoints change while authorization is in progress, the callback is refused with 409; start again. The CLI does this in one step with ephemeral oauth connect NAME.

Connection catalog

GET/v1/catalog/connections

Available to every role. Lists the connections runs can reference, without URLs or authentication settings.

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

Access to saved connections is organization-wide. Every member can use every saved connection by name; there are no per-member grants.