Secrets e Variáveis de Ambiente

Gerencie chaves de API e variáveis de ambiente para o seu backend Convex.

Clique no botão Settings na barra de ferramentas do builder para abrir o painel de configurações. Ele possui três seções:

Seção	Para que serve
General	Nome do projeto e base de conhecimento
SEO & sharing	Define o título do site, descrição e favicon
Secrets	Variáveis de ambiente para o seu backend Convex

Como adiciono um secret?

1. Clique no botão Settings na barra de ferramentas do builder
2. Abra a aba Secrets
3. Insira um nome (como STRIPE_SECRET_KEY) e o valor
4. Clique em Add

Como uso os secrets no meu app?

Os secrets são sincronizados com o backend Convex do seu app. Referencie-os no código de action/mutation/query do Convex com process.env.SECRET_NAME. Eles NÃO estão disponíveis no seu código de frontend nem como variáveis de ambiente em nível de pod — isso evita que os secrets vazem para o bundle do navegador.

A IA usa seus secrets automaticamente ao construir funcionalidades:

• "Accept payments with Stripe" → usa o seu STRIPE_SECRET_KEY
• "Send emails with Resend" → usa o seu RESEND_API_KEY
• "Add Google OAuth" → usa o seu GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET

Os secrets são acessíveis apenas nas funções do seu backend Convex (actions e mutations), não no código React do frontend. A IA gera funções Convex que os leem via process.env.

Posso visualizar/editar um secret depois de criá-lo?

Os valores dos secrets são mascarados por padrão. Você pode alternar a visibilidade para revelar os valores, atualizá-los ou excluí-los e recriá-los.

A IA consegue ver meus secrets?

A IA pode ver os nomes dos seus secrets, mas não os valores. Isso permite que ela referencie a variável de ambiente correta ao construir funcionalidades sem expor dados sensíveis.

Detecção de Chaves Sensíveis

O Proyecta detecta automaticamente padrões comuns de chaves sensíveis (chaves de API, tokens, senhas) e mascara seus valores na interface.

Metadados do Site

A seção SEO & sharing permite configurar:

• Site title — aparece na aba do navegador e nos resultados de busca
• Site description — utilizada para meta descrições de SEO
• Favicon — o ícone exibido nas abas do navegador

Essas configurações são armazenadas no seu projeto e aplicadas quando você fizer o publish.

Base de Conhecimento

A seção Knowledge Base permite adicionar materiais de referência e contexto que a IA utiliza ao construir seu app. Adicione diretrizes de marca, especificações técnicas ou qualquer outra documentação que ajude a IA a tomar melhores decisões.

Perguntas Frequentes

Os secrets são criptografados?

Os secrets são armazenados no seu projeto e sincronizados com o seu deployment Convex. Eles nunca aparecem no código que você commita.

Posso ter secrets diferentes para desenvolvimento e produção?

Atualmente, os secrets se aplicam tanto ao seu ambiente de desenvolvimento quanto ao seu deployment Convex publicado (produção). O gerenciamento de secrets por ambiente está planejado para uma versão futura.

E se eu expuser um secret acidentalmente?

Exclua o secret antigo imediatamente, revogue a chave junto ao provedor terceiro e crie um novo.

Qual é a diferença entre secrets e connectors?

Secrets são variáveis de ambiente brutas que você gerencia por conta própria. Connectors são integrações gerenciadas em que o Proyecta cuida do armazenamento de credenciais, autenticação, renovação de tokens e registro de auditoria para você. Use connectors quando estiverem disponíveis (Stripe, Slack, Resend, ElevenLabs); use secrets para serviços que ainda não possuem um connector.