Armazene as credenciais privadas do seu app em Atoms Cloud → Chaves para manter seus valores fora do Chat e do código-fonte, e para gerenciar valores separados de Teste e Produção.

Antes de usar Chaves, conecte o projeto ao Atoms Cloud. Se ele não estiver conectado, peça ao Agente para conectar o Atoms Cloud ou siga Atoms Cloud.

Usar uma chave no Atoms Cloud

Antes de começar

Antes de adicionar uma chave, certifique-se de que:

• Você está usando o Atoms na web para desktop.
• O projeto está conectado ao Atoms Cloud.
• Você é proprietário do espaço de trabalho. Somente proprietários do espaço de trabalho podem adicionar novas chaves.

Se Chaves ou Nova Chave não estiver disponível, confirme que você abriu o projeto pretendido e que ele está conectado ao Atoms Cloud. Se Nova Chave continuar indisponível, confirme que você é proprietário do espaço de trabalho. Se o Atoms mostrar uma mensagem de disponibilidade de plano ou uso, siga a disponibilidade na tela ou o caminho de atualização e tente novamente.

Adicionar uma chave de Teste

1. Abra o projeto em um dispositivo desktop.
2. Na mesma barra de ferramentas do espaço de trabalho onde está o Visualizador de App , selecione Atoms Cloud.
3. Selecione Chaves na barra lateral do Atoms Cloud.
4. Abra Chaves de Teste e depois selecione Neste Projeto.
5. Selecione Nova Chave.
6. Preencha os campos obrigatórios:
   • Nome: Insira um nome de referência claro, como RESEND_API_KEY. Use letras, números e sublinhados, e comece com uma letra ou sublinhado.
   • Valor: Insira a credencial exatamente como fornecida pelo provedor.
   • Descrição: Explique para que serve a chave, como Usada para enviar e-mails de conta. Não inclua o valor da credencial.
7. Se você quiser reutilizar a chave em outros projetos, selecione Salvar na Biblioteca.
8. Selecione Adicionar. Quando a chave for salva, o Atoms mostrará Chave adicionada com sucesso.

Adicionar uma chave de Teste

Somente proprietários do espaço de trabalho podem adicionar novas chaves. Se você precisar que uma chave seja adicionada, peça a um proprietário do espaço de trabalho.

Usar uma chave salva no Chat

Faça referência à chave salva em vez de inserir seu valor em uma mensagem.

1. Abra o Chat do projeto na versão desktop do Atoms e digite #.
2. Selecione Chaves.
3. Pesquise a chave salva e selecione seu nome.
4. Diga ao Agente para que serve a chave e o que você quer que a integração faça.

O menu # adiciona uma referência à chave salva sem inserir seu valor na sua mensagem.

Referenciar uma chave salva no Chat

Testar uma chave salva

1. No Visualizador de App, execute uma ação simples que use a chave.
2. Confirme que ela produz o resultado esperado, como entregar um e-mail de teste ou retornar dados de teste.
3. Revise quaisquer erros ou logs visíveis e certifique-se de que eles não exponham o valor da chave.

Se o serviço fornecer chaves separadas de teste e produção, use a chave de teste enquanto estiver criando seu app. Use a chave de produção somente depois que seu app for publicado. Se o teste falhar, verifique o painel do provedor para confirmar que a chave está ativa e tem permissão para executar a ação solicitada. Nunca cole o valor da chave no Chat ao solucionar problemas.

Entenda como as Chaves funcionam

Antes de adicionar chaves, é útil entender o que o Atoms armazena e como proteger suas credenciais.

O que o Atoms armazena

Atoms Cloud → Chaves armazena credenciais que seu app usa para se conectar a serviços externos, como chaves de API e tokens de acesso.

Cada chave salva tem um nome, uma descrição e um valor privado. O nome e a descrição ajudam o Agente a entender quando usar a chave, enquanto o valor privado permanece oculto do Chat.

Onde obter uma chave

O Atoms não cria nem fornece credenciais para serviços externos. Você deve obtê-las com o provedor de serviço relevante. Siga as instruções do provedor ao escolher permissões, testar a chave e verificar se ela expira.

Mantenha credenciais privadas em segredo

Nunca cole uma credencial privada no Chat, no código-fonte, em código executado no navegador, em capturas de tela, logs ou mensagens de suporte. Salve-a em Chaves e depois faça referência à entrada salva pelo nome.

Se um valor privado já tiver sido exposto, trate-o como comprometido e revogue-o ou faça sua rotação por meio do provedor.

Credenciais privadas e seguras para navegador

Chaves não rotula valores salvos como Público ou Privado. Salvar um valor em Chaves não o torna automaticamente seguro para uso em código exposto ao navegador. Se seu app usar o valor no navegador, visitantes poderão inspecioná-lo.

Verifique a documentação do provedor antes de decidir onde usar uma credencial:

• Use um valor em código exposto ao navegador somente quando o provedor declarar explicitamente que é seguro expô-lo.
• Mantenha credenciais privadas em lógica do lado do servidor ou backend, onde elas não ficam expostas aos visitantes do app.

Escolha o ambiente e o armazenamento da chave

Ao adicionar uma chave, você precisa tomar duas decisões separadas:

• Qual ambiente usará a chave.
• Se a chave permanecerá neste projeto ou ficará disponível para outros projetos.

Escolha um ambiente

Opção	Quando é usado
Chaves de Teste	Usadas durante o desenvolvimento e teste do seu app no Visualizador de App. Se você não adicionar um valor de Produção separado, o app publicado também usará o valor de Teste.
Chaves de Produção	Usadas pelo app publicado quando ele exige uma credencial ativa separada. Os valores de Produção são adicionados durante o processo de publicação e gerenciados separadamente dos valores de Teste.

Escolha onde salvar a chave

Opção	Quando usá-la
Neste Projeto	Escolha esta opção para uma chave que deve ser usada apenas pelo projeto atual.
Biblioteca de Chaves	Escolha esta opção quando você quiser intencionalmente reutilizar uma chave em vários projetos. Ao adicionar ou atualizar uma chave de Teste, selecione Salvar na Biblioteca para disponibilizá-la na biblioteca.

O ambiente e o local de armazenamento são independentes. Salvar uma chave de Teste na Biblioteca de Chaves a torna reutilizável, mas não a transforma em um valor de Produção.

Use Neste Projeto por padrão. Salve uma chave na biblioteca somente quando tiver certeza de que ela deve ser compartilhada entre projetos.

Usar um valor de Produção separado

Ao publicar um projeto que usa uma chave salva, o fluxo de publicação pode pedir que você configure Chaves de Produção. Por padrão, o app publicado usa o valor de Teste. Para usar uma credencial diferente, selecione Produção e salve um valor separado para a chave.

Use um valor de Produção separado quando:

• O provedor fornecer credenciais diferentes para teste e produção.
• Você não quiser que a credencial usada durante o desenvolvimento seja usada pelo app publicado.

Os valores de Produção são criados por meio do fluxo de publicação. Você não pode criar um selecionando Nova Chave na aba Chaves de Produção. Depois que um valor de Produção for configurado para um app publicado, você poderá visualizá-lo em Atoms Cloud → Chaves → Chaves de Produção.

Depois de publicar ou atualizar o app, repita a jornada de usuário relevante no site publicado para confirmar que a chave de Produção funciona corretamente. Para o processo completo de implantação, consulte Publicar e implantar.

Atualizar ou rotacionar uma credencial

Atualizar um valor de Teste salvo

1. Abra Atoms Cloud → Chaves → Chaves de Teste.
2. Abra Neste Projeto ou Biblioteca de Chaves, dependendo de onde a entrada foi salva.
3. Selecione o Valor ou a Descrição da chave, insira as informações atualizadas e depois selecione Atualizar.
4. Aguarde Salvo com sucesso e depois teste novamente o fluxo afetado.

Rotação planejada de chave

Siga estas etapas quando a credencial existente ainda estiver segura e você quiser substituí-la sem interromper seu app:

1. Crie uma credencial de substituição por meio do provedor de serviço.
2. Substitua o valor de Teste no Atoms e depois teste o recurso afetado no Visualizador de App.
3. Se o app publicado usar um valor de Produção separado, substitua-o e publique a atualização.
4. Teste o mesmo recurso no site publicado.
5. Depois de confirmar que a substituição funciona corretamente, revogue a credencial antiga por meio do provedor.

Se uma credencial puder ter sido exposta

Trate a credencial como comprometida e aja imediatamente:

1. Revogue-a ou desative-a por meio do provedor de serviço.
2. Crie uma credencial de substituição.
3. Atualize os valores relevantes de Teste e Produção no Atoms.
4. Teste novamente os recursos afetados tanto no Visualizador de App quanto no app publicado.
5. Remova quaisquer cópias expostas do código-fonte, do Chat, de capturas de tela e de logs, quando possível.

Excluir uma chave ou remover seu valor do Atoms não revoga a credencial original. Você deve revogá-la por meio do provedor de serviço.

Remover uma credencial

Antes de excluir uma chave salva, certifique-se de que seu app não dependa mais dela:

1. Remova o recurso que usa a chave ou substitua suas referências por outra chave salva.
2. Revogue a credencial original por meio do provedor de serviço para que ela não possa mais ser usada.
3. Abra Atoms Cloud → Chaves, encontre a entrada inativa, selecione Excluir e confirme.

A exclusão de uma chave não pode ser desfeita. Ela também pode quebrar pré-visualizações ou checkpoints antigos que ainda fazem referência a ela. Se Excluir não estiver disponível, a chave ainda estará marcada como ativa. Remova ou substitua todas as referências a ela antes de tentar novamente.

FAQ

Minha chave de Teste funciona no Visualizador de App, mas não depois da publicação. Por quê?

Se sua chave de Teste funciona no Visualizador de App, mas o app publicado falha porque uma chave está ausente ou vazia:

1. Verifique se o valor relevante de Teste ou Produção foi salvo antes ou depois da última publicação. Se ele foi salvo depois, publique novamente para que a alteração tenha efeito.
2. Verifique se a chave salva tem o valor correto de Teste ou Produção. O app publicado usa o valor de Teste, a menos que um valor de Produção separado esteja configurado.
3. Revise os erros do serviço downstream em busca de pistas. “Unauthorized” normalmente indica uma chave vazia ou incorreta para aquele ambiente.

Se o problema persistir, entre em contato com o Suporte e inclua:

• Link do projeto ou URL ativa
• O nome da chave afetada e se o problema está no valor de Teste ou Produção
• O erro completo do serviço downstream
• Uma captura de tela sanitizada da página de configuração
• Se a configuração da chave foi salva antes ou depois da publicação

Importante: Forneça apenas nomes de chaves. NÃO envie valores secretos, senhas ou tokens.