Integrações

A tela de Integrações reúne todos os pontos de conexão da Adalink com sistemas externos. São seis abas, cada uma para um caso de uso diferente. Você não precisa conhecer todas — entre na que faz sentido para o que está montando agora.

API Keys — para o seu sistema falar com a Adalink

Quando você quer integrar a Adalink com um sistema seu (um aplicativo interno, um site, um automatizador) sem ter que fazer login a cada chamada, você gera uma API Key. É uma chave permanente do tipo ada_xxx que viaja no header x-ada-token de cada requisição. Dê um nome que ajude a lembrar onde está sendo usada ("Produção", "Staging", "Meu App") — porque o token aparece só uma vez na criação. Se vazar, basta revogar e criar outra.

Aba API Keys — chaves para integração com sua aplicação

Credenciais — chaves dos provedores de IA

Aqui você coloca suas próprias API keys de OpenAI, Anthropic, Google, Mistral, Groq. Útil quando sua empresa já tem contrato com um provedor e quer que os agentes da Adalink usem aquela chave (em vez do crédito padrão da plataforma). Cada provedor tem o botão Configurar — você cola a chave (sk-..., etc.) e pronto, todos os agentes da organização passam a usá-la para os modelos daquele provedor.

Não confunda com API Keys: API Key é a chave do SEU sistema para chamar a Adalink. Credencial é a chave do PROVEDOR (OpenAI, etc.) para a Adalink chamar o modelo dele.

Conectores — contas externas (Google, Microsoft, Notion)

É aqui que você autoriza a plataforma a agir nas suas contas de e-mail, calendário, drive ou Notion. Funciona em três modos diferentes — escolha o que faz mais sentido para o seu caso:

Aba Conectores — contas OAuth conectadas

OAuth (sua conta)

O fluxo clássico: clica e autoriza a Adalink em uma janela do provedor (Google, Microsoft, Notion). Ideal para uso individual ou times pequenos. A autorização vale enquanto você não revogar.

Service Account (cole JSON)

Para empresas que já têm Service Account configurada no Google Cloud ou Azure. Você cola o JSON (Google) ou os IDs (tenant/client/secret no Microsoft). Útil quando o agente precisa rodar sem nenhum humano logado — exemplo: indexação noturna de pastas compartilhadas.

Compartilhar via email (só Google)

A Adalink mostra um e-mail dela e você compartilha pastas/arquivos do Drive com esse e-mail. Sem precisar de credencial nem JSON. Mais seguro — você dá só o que quer que ela enxergue — em troca de um pouco mais de trabalho para configurar.

Métodos para conectar uma conta Microsoft

Os conectores alimentam ferramentas dos agentes (gmail.send, drive.read, calendar.create...). Quando uma ação precisa de uma conta, a plataforma escolhe automaticamente o conector com escopo certo. Você pode ter várias contas conectadas no mesmo provedor.

Customizadas — APIs próprias

Tem um endpoint HTTP interno que você quer que o agente chame? Aqui você registra o nome (ex: "Buscar CEP"), a URL e o método (GET, POST, PUT, PATCH, DELETE). A partir daí, qualquer agente da organização pode usar essa chamada como uma ferramenta.

Aba Customizadas — tools HTTP da organização

Modal Nova integração customizada — nome, URL e método

MCP Servers — protocolo aberto para extensões

MCP (Model Context Protocol) é um padrão aberto criado pela Anthropic para expor ferramentas e recursos a modelos de IA. Aqui você conecta servidores MCP de terceiros (GitHub MCP, Slack MCP, etc.) — cada um traz um conjunto de novas capacidades para os seus agentes, sem você ter que codar tool por tool. Tem o seu Catálogo público (servidores oficiais publicados na MCP Registry) e os Meus MCP Servers (os que você configurou).

Aba MCP Servers — meus servidores e catálogo público

Adicionar um servidor MCP

Informe nome, URL do servidor, transporte (HTTP é o recomendado) e como autenticar (sem auth, Bearer token ou API key). Se o servidor exige headers customizados (X-Tenant-Id, Authorization), adicione na seção Headers customizados.

Modal Novo MCP Server — configuração básica

Adicionando um header customizado (Authorization: Bearer ...)

Já uso MCP no Claude Desktop / Cursor / Windsurf — posso aproveitar?

Sim. Cole o conteúdo do seu mcp.json no botão Importar JSON e a Adalink reconhece o mesmo formato — todos os servidores entram de uma vez na lista, prontos para uso pelos agentes.

Modal Importar mcp.json — copie do Claude Desktop, Cursor ou Windsurf

Auditoria — quem fez o quê

Toda chamada que um agente faz para uma integração externa (mandar e-mail, criar evento, ler arquivo) fica registrada aqui. Você vê quando aconteceu, qual foi a ação (gmail.send, drive.read...), quem disparou (usuário ou sistema), se deu certo, e quanto tempo levou. Use os filtros para investigar — "todas as falhas no Google na última semana" — e identificar abuso, integrações com problema ou padrões inesperados.

Aba Auditoria — histórico de execuções de tools

Privacidade: o conteúdo da chamada (corpo do e-mail, texto da mensagem) NÃO é gravado — só o hash. A auditoria mostra metadados (ação, sucesso/falha, duração) para debug e compliance, sem expor dado sensível.

Para quem é útil

Quem integra a Adalink com sistemas próprios — começa pela aba API Keys.
Times de operação — usam Conectores para dar acesso a contas corporativas (Drive, Outlook, Notion).
Devs avançados — montam tools customizadas e plugam servidores MCP da organização.
Compliance / segurança — vivem na Auditoria para auditar o uso real.

As Integrações expõem quatro grupos principais de endpoints: /gateway/app-tokens (API Keys), /v1/integrations/* (conectores OAuth, Service Account e auditoria), /v1/org-settings/mcp-servers/* (servidores MCP) e o catálogo público em /v1/org-settings/mcp-servers/catalog.

API Keys (x-ada-token)

Tokens permanentes para o seu sistema chamar a API da Adalink. O token é mostrado uma única vez na criação — guarde com segurança. Use no header x-ada-token em vez do JWT de sessão.

curl

# Criar uma API Key
curl -X POST https://api.adalink.ai/gateway/app-tokens \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "app_id": "web-platform", "description": "Producao", "scopes": ["all"] }'

# Usar em chamadas a partir do seu sistema
curl https://api.adalink.ai/v1/agents \
  -H "x-ada-token: ada_nBGD..."

# Revogar
curl -X DELETE https://api.adalink.ai/gateway/app-tokens/TOKEN_ID \
  -H "Authorization: Bearer SEU_TOKEN"

Conectores OAuth + Service Account

Statuses possíveis: ACTIVE, ERROR, EXPIRED, REVOKED. Use /v1/integrations/{id}/test para validar saúde antes de uma chamada crítica. O endpoint /best-for-action retorna a conexão mais recente que cobre os escopos de uma ação específica (ex: gmail_send).

curl

# 1) Iniciar fluxo OAuth
curl -X POST https://api.adalink.ai/v1/integrations/oauth/authorize \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google", "scopes": ["gmail.send", "calendar.events.create"] }'
# Resposta: { authUrl, state } — redirecionar usuario para authUrl

# 2) Apos retorno, trocar code por conexao
curl -X POST https://api.adalink.ai/v1/integrations/oauth/exchange \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "GOOGLE_CODE", "state": "CSRF_STATE" }'

# 3) Conexao via Service Account (cole o JSON)
curl -X POST https://api.adalink.ai/v1/integrations/service-account \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google", "credentials": { /* JSON da SA */ }, "subject": "user@dominio.com" }'

# Conexao mais recente com escopo certo para uma acao
curl "https://api.adalink.ai/v1/integrations/best-for-action?actionName=gmail_send" \
  -H "Authorization: Bearer SEU_TOKEN"

MCP Servers

Transportes: stdio (binário local), sse (Server-Sent Events), streamable-http (HTTP, padrão). O backend tem circuit breaker — após várias falhas o servidor entra em degraded e pausa automaticamente; /test força nova tentativa.

curl

# Criar servidor MCP
curl -X POST https://api.adalink.ai/v1/org-settings/mcp-servers \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notion MCP",
    "url": "https://mcp.notion.example.com",
    "transport": "streamable-http",
    "auth": { "type": "bearer", "token": "ntn_xxx" },
    "headers": [{ "key": "X-Tenant-Id", "value": "minha-org" }]
  }'

# Importar formato Claude Desktop / Cursor / Windsurf
curl -X POST https://api.adalink.ai/v1/org-settings/mcp-servers/import-json \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpServers": {
      "github": { "url": "https://mcp.github.example.com/sse", "headers": { "Authorization": "Bearer ghp_xxx" } }
    }
  }'

# Testar saude
curl -X POST https://api.adalink.ai/v1/org-settings/mcp-servers/SERVER_ID/test \
  -H "Authorization: Bearer SEU_TOKEN"

Auditoria

Paginação cursor-based via before (timestamp ISO). Filtros suportados: provider, actionName, success, limit (máx 50). Apenas metadados são gravados — body da chamada vai como hash SHA-256.

curl

# Listar execucoes (paginacao por cursor)
curl "https://api.adalink.ai/v1/integrations/audit-log?limit=50&provider=GOOGLE&actionName=gmail_send&success=false" \
  -H "Authorization: Bearer SEU_TOKEN"

# Resposta inclui: actionName, provider, success, errorCode, durationMs, userId, inputHash, createdAt