Variáveis de ambiente (.env): onde guardar senha e chave sem colar no código

Você colou a API key no meio do script, rodou, funcionou. Depois mandou o arquivo no WhatsApp da equipe “só pra alinhar o fluxo”. Alguém tirou print. Outra pessoa subiu o mesmo script no Git. Em poucos minutos a chave estava em três lugares que não deveriam existir: chat, histórico e repositório.

Isso é comum quando a gente começa a automatizar. A pressa de “fazer funcionar” vence o hábito de separar o que é código do que é segredo. O pedido certo é simples: o programa lê a chave do ambiente. O retorno também: ele conecta na API, no webhook ou no banco sem expor a senha no arquivo que você compartilha.

Neste tutorial você vai entender o básico de variável de ambiente e do arquivo .env, ver como isso fica em Node e em Python, e onde o mesmo cuidado aparece em Make, Zapier e n8n. Sem hype. Só o que precisa para parar de colar chave no código.

O que é variável de ambiente

Variável de ambiente é um par nome = valor que fica fora do código. O programa pergunta pelo nome e recebe o valor na hora da execução. Você muda a chave sem reescrever o script. Você compartilha o script sem compartilhar a senha.

O arquivo .env é a forma local mais comum de guardar esses pares no seu computador ou no servidor. Ele fica na pasta do projeto, em texto simples, e costuma ter linhas assim:

API_KEY=SUA_CHAVE_AQUI

WEBHOOK_URL=https://exemplo.com/hook

Cada linha é um nome e um valor. O código não “conhece” a chave de verdade. Ele só pede API_KEY ou WEBHOOK_URL e usa o que o ambiente devolver. Em Node isso costuma ser process.env.API_KEY. Em Python, os.getenv("API_KEY").

Por que isso importa para quem automatiza? Porque automação quase sempre precisa de credencial: token de API, URL de webhook, senha de SMTP, ID de conta. Se esses valores ficam escritos no script, qualquer cópia do arquivo vira cópia do segredo. Se ficam no ambiente, o arquivo que você manda no chat ou sobe no Git pode ser o mesmo para todo mundo, e cada pessoa (ou cada máquina) coloca o próprio .env local.

O .env não é mágica. Ele não criptografa sozinho. Ele é um arquivo local que você não deve versionar. A proteção real é: não commitar, não colar no chat, não publicar no artigo, e girar a chave se ela já vazou. O .env só organiza o lugar certo para o valor viver.

Pense no fluxo em duas camadas. Camada 1: o código diz “preciso de API_KEY”. Camada 2: o ambiente responde com o valor. O pedido é o nome. O retorno é o valor na memória do processo, não um trecho permanente no meio da lógica. Quando alguém abre o script, vê a intenção. Não vê a senha.

Se você ainda está montando os primeiros fluxos de automação e quer um mapa mais amplo de como organizar scripts e ferramentas, o guia de automação para iniciantes no Camada Prática ajuda a encaixar esse hábito no dia a dia sem complicar o restante do setup.

Como fica na prática

Imagine um script que chama uma API e dispara um webhook. Sem variável de ambiente, alguém cola a chave no meio do arquivo. Com variável de ambiente, o .env local guarda:

API_KEY=SUA_CHAVE_AQUI

WEBHOOK_URL=https://exemplo.com/hook

No código Node, depois de carregar o .env (com dotenv ou com a forma nativa do runtime), você usa process.env.API_KEY e process.env.WEBHOOK_URL. No código Python, você usa os.getenv("API_KEY") e os.getenv("WEBHOOK_URL"). O texto do script fala só dos nomes. Os valores reais ficam no arquivo que não vai para o Git e não vai para o WhatsApp.

O pedido do programa é: “me dá o valor de API_KEY”. O retorno esperado é a string da chave, usada na hora da requisição. Se a variável não existir, o retorno costuma ser undefined (Node) ou None (Python). Aí o script deve falhar de forma clara: “API_KEY não definida”, em vez de tentar autenticar com vazio e gerar erro confuso na API.

Na prática isso muda o que você compartilha. Você pode mandar o script com process.env.API_KEY. A equipe cria o próprio .env com API_KEY=SUA_CHAVE_AQUI (cada um com a chave dela, ou com a chave do ambiente de teste). O mesmo vale para WEBHOOK_URL: a URL de teste e a URL de produção ficam em arquivos diferentes, no mesmo código.

Um detalhe útil: trate o .env como configuração local, não como documentação pública. No repositório, o que costuma ir é um .env.example com os nomes e placeholders. Exemplo de conteúdo seguro para exemplo: API_KEY=SUA_CHAVE_AQUI e WEBHOOK_URL=https://exemplo.com/hook. Assim quem clona o projeto sabe o que preencher, sem receber segredo de verdade.

Outro detalhe: nomes em maiúsculas com underscore são convenção, não regra absoluta. API_KEY, WEBHOOK_URL, SMTP_PASSWORD são fáceis de ler e de achar no código. Evite nomes genéricos demais como KEY ou SENHA se o projeto tiver mais de uma credencial. Nome claro reduz erro na hora de ler o ambiente.

Quando o script roda, o ambiente “injeta” esses valores no processo. Você não precisa abrir o .env manualmente a cada linha. Você configura uma vez, sobe o processo, e o runtime devolve o valor quando o código pergunta. Pedido: nome da variável. Retorno: valor usado na conexão, sem aparecer no código-fonte que você versiona ou encaminha.

Passo a passo para quem automatiza

1. Crie um arquivo chamado .env na raiz do projeto (a mesma pasta onde está o script principal).

1. Coloque as linhas com placeholders primeiro, para não misturar valor real com rascunho. Exemplo: API_KEY=SUA_CHAVE_AQUI e WEBHOOK_URL=https://exemplo.com/hook. Depois substitua pelos valores reais só na sua máquina.

1. Adicione .env no .gitignore. Se o repositório ainda não tem .gitignore, crie um e inclua a linha .env. Confirme que o arquivo não aparece como candidato a commit.

1. No Node, instale e use dotenv no início do script (ou use o carregamento de env do seu runtime, se já estiver configurado). Leia com process.env.API_KEY. Se vier vazio, interrompa com mensagem objetiva.

1. No Python, carregue o .env com python-dotenv (ou exporte as variáveis no shell antes de rodar). Leia com os.getenv("API_KEY"). Trate ausência do valor como erro de configuração, não como detalhe cosmético.

1. Teste o pedido e o retorno. Pedido: o script pede API_KEY e WEBHOOK_URL. Retorno esperado: autentica na API e envia o webhook sem a chave escrita no arquivo .js ou .py. Um teste simples é imprimir só se a variável existe (verdadeiro ou falso), nunca o valor completo no log compartilhado.

1. Separe ambiente de teste e ambiente real. Use um .env local para desenvolvimento. Em produção, configure as mesmas variáveis no painel do servidor, do container ou da plataforma de deploy. O nome fica igual. O valor muda conforme o ambiente.

Checklist rápido antes de compartilhar o projeto:

• O .env está no .gitignore?
• Existe um .env.example só com placeholders?
• O código usa process.env... ou os.getenv(...) em vez de string literal da chave?
• Você evitou logar a chave inteira no console?
• Se a chave já foi colada em chat ou commit, você já planejou girar (revogar e criar outra)?

Esse passo a passo é o mínimo viável. Não precisa de ferramenta nova só por estética. Precisa do hábito: segredo fora do código, nome dentro do código, valor só no ambiente.

Se você está organizando scripts e pastas pela primeira vez, vale cruzar isso com o material de organização de projetos de automação no blog: o .env funciona melhor quando o projeto já tem um lugar claro para config local e um lugar claro para código compartilhado.

Onde isso aparece em Make, Zapier, n8n

Quem automatiza só com código encontra .env cedo. Quem monta cenário em ferramenta visual encontra o mesmo princípio com outro nome: campo de credencial, connection, secret ou variável de ambiente da instância.

No Make, você conecta apps com conexões salvas. A chave fica na conexão, não no meio do módulo de texto do cenário. Se você cola o token num campo de body “só para testar”, está hardcodando de novo. O pedido correto é usar a conexão autenticada. O retorno é a chamada autorizada sem o token exposto no blueprint que você exporta ou compartilha.

No Zapier, o caminho parecido é a Connection ou as autenticações de cada app. Há também variáveis de ambiente em contas e contextos de equipe, conforme o plano e o produto. A regra prática permanece: não cole sk-exemplo no meio de um passo de Formatter ou de Code se esse valor é segredo. Guarde na autenticação ou em recurso pensado para segredo.

No n8n, você tem Credentials e também variáveis de ambiente da instância. Credenciais são o lugar padrão para API keys e tokens. Expressões do fluxo devem referenciar a credencial, não uma string fixa com a chave. Em self-hosted, variáveis de ambiente do servidor cobrem valores de sistema. De novo: pedido pelo nome da configuração, retorno na execução, sem hardcode no JSON do workflow.

Em todas essas ferramentas o erro clássico é o mesmo do script: colar a chave no campo visível do cenário para “ir mais rápido”. O cenário vira arquivo compartilhável. O print vira vazamento. O export vira backup do segredo. Trate credencial como credencial. Trate texto do cenário como lógica, não como cofre.

Resumo operacional para no-code e low-code:

• Use o gerenciador de credenciais da ferramenta.
• Evite token no corpo da requisição montado à mão, salvo quando a API exige e mesmo assim prefira campo mascarado ou expressão ligada à credencial.
• Ao compartilhar cenário, revise se algum nó ainda tem placeholder trocado por valor real.
• Em equipe, cada pessoa (ou cada ambiente) deve ter a própria conexão de teste quando fizer sentido.

O conceito não muda porque a interface mudou. Variável de ambiente, secret e credential são o mesmo gesto: separar o valor sensível da receita do fluxo.

O que NÃO fazer

Não commite o .env. Se o Git já rastreou o arquivo, removê-lo depois não apaga o histórico sozinho. A chave pode continuar em commits antigos. Nesse caso, trate como vazamento: gire a chave no painel do serviço e limpe o histórico com cuidado (ou aceite que o segredo antigo morreu e só a chave nova vale).

Não cole chave no corpo de artigo, tutorial, ticket ou chat “por um minuto”. Print de terminal com token completo também conta. Se precisa debugar com outra pessoa, mostre só os últimos caracteres ou confirme que a variável está definida, sem colar o valor.

Não reutilize a mesma chave em tudo. Uma chave para o script de teste, outra para produção, outra para um app paralelo, quando o serviço permitir. Se uma vazar, você isola o dano. Se uma única chave abre todos os fluxos, um print no WhatsApp derruba o conjunto.

Não confunda .env.example com .env. O example é público e usa SUA_CHAVE_AQUI, sk-exemplo, senha-exemplo, https://exemplo.com/hook. O .env real fica fora do versionamento.

Não logue o segredo em ferramenta de observabilidade. Erro de autenticação pode registrar headers ou body. Revise o que o seu script imprime em caso de falha.

Não compartilhe o .env por e-mail ou drive “temporário”. Temporário vira permanente no histórico. Prefira cada pessoa criar o arquivo local, ou use o cofre/secret manager da equipe se já existir processo para isso.

O .env também não deve ir para o repositório. Se commit e remoto ainda são termos vagos, veja Git para quem não programa.

O que fazer agora

Escolha UMA chave que hoje está colada no código. Mova só essa. Crie ou edite o .env com o nome certo e o valor real só na sua máquina. Troque a string literal por process.env.NOME ou os.getenv("NOME"). Rode o script. Confirme o pedido (nome da variável) e o retorno (conexão ok sem a chave no arquivo).

Se essa chave já apareceu em print, Git ou chat da equipe, gire a chave antiga agora: revogue no painel do provedor, crie outra, atualize só o .env (ou a credencial no Make, Zapier ou n8n). Não espere “quando tiver tempo”. O vazamento já aconteceu. O giro é o fechamento.

Depois disso, adicione .env ao .gitignore, publique um .env.example com placeholders e revise o próximo cenário visual com o mesmo critério. Um hábito pequeno evita o vazamento grande. Código compartilha lógica. Ambiente guarda segredo.