Conexões · Documentação da Ephemeral

Salve conexões HTTP e MCP, autorize conexões OAuth e liste o que as execuções podem usar. Configurar conexões exige uma chave de administrador ou um proprietário ou administrador conectado; os membros podem ler o catálogo. Veja as conexões para saber como as chamadas são intermediadas.

Salvar uma conexão

PUT/v1/connections/{name}

Cria a conexão ou a substitui, se o nome já existir. Os nomes seguem as mesmas regras dos nomes de fluxos de trabalho. Somente proprietário ou administrador.

Corpo

typestringobrigatório

http ou mcp.

urlstringobrigatório

URL base HTTPS da API ou endpoint Streamable HTTP do servidor MCP. Deve resolver para um endereço público.

authobject

Como autenticar. Omita para nenhuma.

allowed_methodsstring[]

Conexões HTTP: métodos que as execuções podem usar, como ["GET"]. Vazio permite todos.

allowed_toolsstring[]

Conexões MCP: nomes das ferramentas que as execuções podem chamar. Vazio permite todas.

instructionsstring

Como o agente deve usar a API: endpoints, formatos de requisição, convenções. São mostradas ao agente, então não inclua segredos. Até 4.000 caracteres.

O objeto auth

typestring

none, bearer, header, basic ou oauth2.

tokenstring

Para bearer e header.

headerstring

Para header: o nome do cabeçalho, como X-API-Key.

username, passwordstring

Para basic. O nome de usuário não pode conter dois-pontos.

client_idstring

Para oauth2. Obrigatório, junto com authorization_url e token_url.

client_secretstring

Para clientes oauth2 que têm um.

authorization_url, token_urlstring

Os endpoints OAuth do provedor. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post ou none.

scopesstring[]

Escopos a solicitar.

resourcestring

Indicador de recurso opcional enviado com a requisição de autorização.

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

A resposta é {"name": "...", "type": "..."}. O Ephemeral valida a URL e o formato das credenciais antes de salvar.

Para atualizar uma conexão sem reenviar seus segredos, salve-a sem os campos secretos e com o mesmo auth.type. O token, a senha, o segredo do cliente e os tokens OAuth armazenados são mantidos. Alterar auth.type substitui toda a autenticação.

Listar conexões

GET/v1/connections

Somente proprietário ou administrador. Retorna todas as conexões com name, type, url, allowed_methods, allowed_tools, authenticated e as partes não secretas de auth.

Obter uma conexão

GET/v1/connections/{name}

Somente proprietário ou administrador. Retorna a configuração sem as credenciais e com os valores de consulta das URLs mascarados.

Excluir uma conexão

DELETE/v1/connections/{name}

Somente proprietário ou administrador. Retorna 204 No Content.

Uma execução que referencia uma conexão excluída, diretamente ou por um fluxo de trabalho, é rejeitada quando você a cria. Uma execução já em andamento perde o acesso na próxima vez que chamar a conexão.

Autorizar uma conexão OAuth

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

Somente proprietário ou administrador. Retorna {"url": "..."}, a página de autorização do provedor.

Abra a URL em um navegador e aprove o acesso. O provedor redireciona para /oauth/callback no mecanismo, o Ephemeral troca o código e armazena os tokens, e o navegador volta ao painel. Cada URL funciona uma única vez. Registre https://app.ephemer.al/oauth/callback como URI de redirecionamento no seu provedor ou, em uma instalação auto-hospedada, o seu próprio domínio.

Se o ID do cliente ou os endpoints OAuth da conexão mudarem enquanto a autorização está em andamento, o callback é recusado com 409; comece de novo. A CLI faz isso em uma única etapa com ephemeral oauth connect NAME.

Catálogo de conexões

GET/v1/catalog/connections

Disponível para todas as funções. Lista as conexões que as execuções podem referenciar, sem URLs nem configurações de autenticação.

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

O acesso às conexões salvas vale para toda a organização. Todo membro pode usar qualquer conexão salva pelo nome; não há concessões por membro.