Em uma implantação auto-hospedada, as integrações não funcionam até você registrar seu próprio aplicativo OAuth em cada serviço. A plataforma hospedada do Studio já vem com credenciais para todas as integrações; uma instância auto-hospedada não vem com nenhuma. Os usuários vão ver o conector na interface, clicar em "Connect" e receber um erro do provedor até que o *_CLIENT_ID e o *_CLIENT_SECRET correspondentes estejam definidos.
Você só precisa registrar os serviços que seu time realmente usa. Um único app OAuth cobre todos os conectores do Studio que compartilham aquela credencial — um único app do Google atende Gmail, Drive, Sheets, Calendar, Docs, Forms, BigQuery e mais.
Como funciona
Cada conector tem um provider ID. Quando um usuário conecta uma conta, o Studio o redireciona para o provedor, e o provedor redireciona de volta para:
https://<your-studio-domain>/api/auth/oauth2/callback/<provider-id>Essa URL é derivada de NEXT_PUBLIC_APP_URL, então defina-a corretamente antes de registrar qualquer coisa — a redirect URI que você registra no provedor precisa coincidir byte a byte, incluindo o esquema e a ausência de barra no final.
A maioria dos provedores permite registrar várias redirect URIs em um mesmo app. Registre sua URL de produção e qualquer URL de staging juntas, para que um app OAuth atenda os dois ambientes.
Configuração
Confirme sua URL pública
NEXT_PUBLIC_APP_URL=https://studio.yourdomain.com
BETTER_AUTH_URL=https://studio.yourdomain.comAs duas precisam ser a sua origem pública real. Se estiverem erradas, todo ciclo de OAuth falha com erro de redirect URI incompatível.
Registre um app no provedor
No console de desenvolvedor do provedor, crie um aplicativo OAuth 2.0. Registre a(s) redirect URI(s) de cada conector do Studio que você quer daquele provedor — uma linha por provider ID das tabelas abaixo.
Para um app do Google que cobre Gmail e Drive, por exemplo, você registra as duas:
https://studio.yourdomain.com/api/auth/oauth2/callback/google-email
https://studio.yourdomain.com/api/auth/oauth2/callback/google-driveOs escopos são solicitados pelo Studio no momento da autorização; em geral você não precisa declará-los antes, mas Google e Microsoft exigem que você habilite as APIs correspondentes no projeto/app primeiro (por exemplo, Gmail API, Drive API, Calendar API).
Defina as credenciais
Adicione o client ID e o secret ao ambiente da aplicação. No Kubernetes eles vão em app.env — o chart escreve todas as chaves de lá em um Secret gerenciado por ele — mas forneça os valores via External Secrets ou por um Secret criado previamente, em vez de commitá-los em um arquivo de values:
app:
env:
GOOGLE_CLIENT_ID: "..."
GOOGLE_CLIENT_SECRET: "..."
SLACK_CLIENT_ID: "..."
SLACK_CLIENT_SECRET: "..."Reinicie a aplicação. As credenciais são lidas na inicialização — um pod em execução não vai captar credenciais novas.
Verifique
Abra um workflow, adicione o bloco da integração e conecte uma conta. Um ciclo bem-sucedido devolve você ao Studio com a conta listada. Uma redirect URI incompatível é a falha que você vai encontrar mais vezes; compare a URI registrada com NEXT_PUBLIC_APP_URL caractere por caractere.
Referência de provedores
Todo provider ID abaixo mapeia para a redirect URI https://<your-domain>/api/auth/oauth2/callback/<provider-id>.
Um único client OAuth no Google Cloud Console cobre todos estes. Habilite a API correspondente para cada conector que você usar.
| Variáveis de ambiente | Provider IDs |
|---|---|
GOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRET | google-email, google-drive, google-sheets, google-docs, google-calendar, google-contacts, google-forms, google-tasks, google-meet, google-groups, google-ads, google-bigquery, google-vault, vertex-ai |
As mesmas variáveis também alimentam o "Sign in with Google". Veja Autenticação.
Microsoft
Um único registro de app no Entra ID cobre todos estes.
| Variáveis de ambiente | Provider IDs |
|---|---|
MICROSOFT_CLIENT_IDMICROSOFT_CLIENT_SECRET | outlook, onedrive, sharepoint, microsoft-teams, microsoft-excel, microsoft-planner, microsoft-dataverse, microsoft-ad |
As mesmas variáveis também alimentam o "Sign in with Microsoft".
Todo o resto
| Serviço | Variáveis de ambiente | Provider ID |
|---|---|---|
| Slack | SLACK_CLIENT_ID / SLACK_CLIENT_SECRET | slack |
| Notion | NOTION_CLIENT_ID / NOTION_CLIENT_SECRET | notion |
| Jira | JIRA_CLIENT_ID / JIRA_CLIENT_SECRET | jira |
| Confluence | CONFLUENCE_CLIENT_ID / CONFLUENCE_CLIENT_SECRET | confluence |
| Linear | LINEAR_CLIENT_ID / LINEAR_CLIENT_SECRET | linear |
| Asana | ASANA_CLIENT_ID / ASANA_CLIENT_SECRET | asana |
| ClickUp | CLICKUP_CLIENT_ID / CLICKUP_CLIENT_SECRET | clickup |
| Monday | MONDAY_CLIENT_ID / MONDAY_CLIENT_SECRET | monday |
| Airtable | AIRTABLE_CLIENT_ID / AIRTABLE_CLIENT_SECRET | airtable |
| HubSpot | HUBSPOT_CLIENT_ID / HUBSPOT_CLIENT_SECRET | hubspot |
| Salesforce | SALESFORCE_CLIENT_ID / SALESFORCE_CLIENT_SECRET | salesforce |
| Pipedrive | PIPEDRIVE_CLIENT_ID / PIPEDRIVE_CLIENT_SECRET | pipedrive |
| Attio | ATTIO_CLIENT_ID / ATTIO_CLIENT_SECRET | attio |
| Zoho Desk | ZOHO_CLIENT_ID / ZOHO_CLIENT_SECRET | zoho-desk |
| Wealthbox | WEALTHBOX_CLIENT_ID / WEALTHBOX_CLIENT_SECRET | wealthbox |
| Box | BOX_CLIENT_ID / BOX_CLIENT_SECRET | box |
| Dropbox | DROPBOX_CLIENT_ID / DROPBOX_CLIENT_SECRET | dropbox |
| DocuSign | DOCUSIGN_CLIENT_ID / DOCUSIGN_CLIENT_SECRET | docusign |
| Zoom | ZOOM_CLIENT_ID / ZOOM_CLIENT_SECRET | zoom |
| Cal.com | Apenas CALCOM_CLIENT_ID — client público com PKCE, sem secret | calcom |
| Webflow | WEBFLOW_CLIENT_ID / WEBFLOW_CLIENT_SECRET | webflow |
| WordPress | WORDPRESS_CLIENT_ID / WORDPRESS_CLIENT_SECRET | wordpress |
LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET | linkedin | |
| X | X_CLIENT_ID / X_CLIENT_SECRET | x |
REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET | reddit | |
| Spotify | SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET | spotify |
| TikTok | TIKTOK_CLIENT_ID / TIKTOK_CLIENT_SECRET | tiktok |
Serviços com um fluxo diferente
| Serviço | Configuração | Observações |
|---|---|---|
INSTAGRAM_CLIENT_ID / INSTAGRAM_CLIENT_SECRET | App ID/Secret do Instagram, obtidos no Meta App Dashboard (Instagram → API setup with Instagram login). Redirect URI: /api/auth/oauth2/callback/instagram. Publicar exige armazenamento de objetos em nuvem — a Meta busca uma URL HTTPS pública, então armazenamento em disco local não funciona. | |
| Facebook Pages | FACEBOOK_APP_ID / FACEBOOK_APP_SECRET, e NEXT_PUBLIC_FACEBOOK_APP_ID na web | App ID/Secret obtidos no Meta App Dashboard. A web faz login pelo SDK JavaScript do Facebook, e o servidor troca o token de curta duração por tokens de página de longa duração. |
| Shopify | SHOPIFY_CLIENT_ID / SHOPIFY_CLIENT_SECRET | Redirect URI: /api/auth/oauth2/callback/shopify. Fluxo de instalação por loja. |
| Trello | TRELLO_API_KEY | Baseado em chave de API, não em OAuth 2.0. Callback: /api/auth/trello/callback. |
Credenciais de integração fora do OAuth
Muitos blocks se autenticam com uma chave de API que o usuário cola no próprio block, e não exigem nada de você.
O Studio também tem um mecanismo de "chave hospedada", configurado com as variáveis {PREFIX}_API_KEY_COUNT + {PREFIX}_API_KEY_1..N abaixo, que permite à plataforma fornecer uma chave para os usuários não precisarem trazer a própria. O caminho de injeção só é ativado quando a implantação é a plataforma hospedada do Studio (isHosted, derivado do hostname da aplicação), então, em uma instância auto-hospedada, essas variáveis não eliminam a necessidade de os usuários trazerem a própria chave. Defina-as apenas se você estiver rodando um fork que adaptou essa checagem.
As variáveis, para referência:
| Variável | Serviço |
|---|---|
EXA_API_KEY (ou EXA_API_KEY_COUNT + EXA_API_KEY_1..N) | Busca Exa |
SERPER_API_KEY | Busca Serper |
BROWSERBASE_API_KEY / BROWSERBASE_PROJECT_ID | Browserbase |
HUNTER_API_KEY_COUNT + HUNTER_API_KEY_1..N | Hunter.io |
PEOPLEDATALABS_API_KEY_COUNT + PEOPLEDATALABS_API_KEY_1..N | People Data Labs |
CONTEXT_DEV_API_KEY_COUNT + CONTEXT_DEV_API_KEY_1..N | Context.dev |
FALAI_API_KEY | fal.ai |
TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_PHONE_NUMBER | Twilio |
AGENTMAIL_API_KEY / AGENTMAIL_DOMAIN | AgentMail |
Provedores que aceitam um _COUNT mais chaves numeradas distribuem as requisições em round-robin entre elas.
Triggers que precisam de configuração extra
Triggers de webhook recebem callbacks do provedor e precisam conseguir verificá-los:
| Variável | Necessária para |
|---|---|
SLACK_SIGNING_SECRET | Verificar assinaturas de eventos e slash commands do Slack |
SLACK_EXTENDED_SCOPES / NEXT_PUBLIC_SLACK_EXTENDED_SCOPES | Solicitar o conjunto ampliado de escopos do Slack |
Sua implantação também precisa ser alcançável pelos servidores do provedor para que triggers de webhook disparem — uma instância do Studio em rede privada pode usar triggers de polling, mas não triggers de webhook. Triggers de polling exigem, além disso, o agendador; veja Jobs em Background.