Uma função de inteligência artificial pode resumir textos, criar rascunhos ou responder perguntas dentro de um aplicativo. Para integrar uma API de IA com segurança, a chave secreta do provedor precisa ficar no servidor. Se ela for incluída no JavaScript, HTML ou aplicativo distribuído, uma pessoa pode inspecionar o pacote e reutilizá-la.

Este guia apresenta uma arquitetura de referência para iniciantes. Ele foi conferido com documentação oficial, mas não descreve um sistema testado nem substitui uma revisão de segurança do aplicativo real.

O fluxo básico: aplicativo, backend e provedor de IA

1. O aplicativo envia uma ação permitida para um endpoint do seu backend.

2. O backend autentica a pessoa e verifica se ela pode executar aquela ação.

3. O servidor valida e limita a entrada, removendo dados que não são necessários.

4. O servidor chama a API de IA usando uma credencial guardada como secret.

5. A resposta é validada e reduzida ao formato esperado antes de voltar ao aplicativo.

O navegador nunca precisa conhecer a chave do provedor. Ofuscar ou “esconder” uma credencial dentro do bundle não a torna secreta. CORS pode controlar quais origens o navegador acessa, mas não substitui autenticação, autorização nem proteção da chave.

Guarde a chave no servidor

Em um Cloudflare Worker, cadastre credenciais como Secrets, não em vars, no código-fonte ou em um arquivo enviado ao site. Para produção, a documentação indica configurar o secret pelo painel ou pelo Wrangler, por exemplo com wrangler secret put NOME_DA_CHAVE.

Para desenvolvimento local, use .dev.vars ou .env na pasta do projeto, não os dois ao mesmo tempo. Inclua o arquivo escolhido no .gitignore e use uma credencial de teste separada da produção. Nunca cole um token real em um exemplo, log, issue ou repositório.

O Secrets Store da Cloudflare pode centralizar credenciais compartilhadas entre produtos compatíveis, mas está em beta aberto segundo a documentação consultada em 27/10/2026. Um primeiro aplicativo normalmente pode começar com o secret vinculado ao próprio Worker; avalie disponibilidade, limites e necessidade de compartilhamento antes de adotar um recurso em beta.

Proteja o endpoint e controle o consumo

• Exija sessão autenticada ou use controles proporcionais ao risco se a função for aberta ao público.

• Autorize cada ação no servidor; não confie em um userId, plano ou permissão enviados pelo navegador.

• Defina tamanho máximo para a entrada, limite a saída e aceite apenas os campos necessários.

• Use cotas por pessoa ou conta, além de limites no provedor de IA, alertas de consumo e um orçamento que possa interromper chamadas.

• Configure timeout e trate respostas 429 e falhas do provedor sem criar ciclos de tentativas.

A API de Rate Limiting da Cloudflare pode ser uma camada de proteção, mas seus limites são aproximados e separados por localidade. Ela não garante sozinha um teto global rígido para a fatura do provedor. Combine-a com limites da conta do próprio provedor e controles de uso no backend. Se precisar de contagem estrita compartilhada entre regiões, escolha uma arquitetura que mantenha e atualize essa contagem de forma coordenada.

Trate a resposta da IA como entrada não confiável

O modelo pode devolver conteúdo incorreto, incompleto ou fora do formato esperado. Valide a estrutura no servidor e mostre texto como texto; não execute automaticamente comandos, código, consultas SQL, HTML ou ações sugeridas pela resposta. Para publicar, enviar mensagens, alterar dados ou executar outra ação importante, peça revisão e confirmação humana.

Também proteja as informações enviadas ao modelo. Envie apenas o contexto necessário, não inclua senhas ou dados de clientes sem uma finalidade legítima, e não guarde prompts e respostas por padrão. Se precisar de logs para investigar falhas, prefira registrar horário, identificador técnico, duração, estado e consumo agregado, sem copiar o conteúdo privado.

Mensagens de erro sem revelar detalhes internos

Se o provedor estiver indisponível, informe que a função não conseguiu concluir o pedido e ofereça uma alternativa. Não mostre ao usuário a resposta bruta do provedor, stack trace, cabeçalhos ou valores de configuração. Registre detalhes técnicos de forma protegida e com retenção definida.

Antes de liberar a integração, verifique ao menos: chave ausente, pessoa sem permissão, entrada vazia ou muito longa, limite de uso, timeout, resposta inválida, erro 429, indisponibilidade do provedor e tentativa de repetir a mesma ação. Faça essa revisão em ambiente de teste e confirme que a credencial não aparece no bundle nem nos logs.

Se o backend for um Worker, veja também o guia sobre publicar um site Astro na Cloudflare Workers e o comparativo de VPS, hospedagem compartilhada e Cloudflare Workers.