Como configurar e usar Secrets nas Funções

Functions
1

Por que usar Secret (e não hardcode)

Tokens, senhas de API e outras credenciais não devem ir no código da função.

Se o valor ficar escrito no index.js:

  • Qualquer um que abra a função na tela vê o segredo.
  • Print de tela, log de console.log e cópia do script vazam o token.
  • Trocar a chave obriga a editar e republicar o código — e o valor antigo continua no histórico da função.
  • O mesmo script não serve para rotacionar credencial sem risco de esquecer um lugar.

O cadastro Funções → Configurações → Secrets guarda o valor criptografado. A função só conhece o nome do secret (ex.: api-parceiro-token) e lê o valor em tempo de execução com keyManager. Assim você:

  1. Rotaciona a chave só no cadastro do Secret, sem mexer no script.
  2. Evita vazar o valor em prints do código.
  3. Usa o mesmo padrão em qualquer função do sistema (integração com API de terceiro, token de parceiro, senha de comparação, etc.).
  4. Separa “o que a função faz” de “qual credencial está valendo agora”.

Use Secret para: chave de API de parceiro, token de autenticação, senha que o script precisa comparar ou enviar.

Não use Secret para: textos de negócio, UUID de kanban/etapa/usuário que não são credencial (esses podem ficar no código ou em configuração visível).

Permissão necessária

Para criar, editar ou ver Secrets na interface, o usuário precisa de permissão de escrita na tabela de Secrets (puca_functions_api_secret).

Sem essa permissão:

  • o menu Funções → Configurações → Secrets pode não aparecer; ou
  • a tela abre, mas você não consegue cadastrar nem alterar registros.

Se você não vê o menu Secrets (ou não consegue salvar), peça ao administrador do ambiente para conceder escrita em puca_functions_api_secret ao seu usuário. Leitura sozinha não basta para cadastrar ou rotacionar o valor.

1. Cadastrar um Secret na UI

  1. Abra o módulo Funções.
  2. No menu, Configurações → Secrets.
  3. Clique para criar um registro.
  4. Preencha:
    • Nome: identificador estável que o código vai usar. Ex.: api-parceiro-token. Sem espaços; não coloque o valor da chave no nome.
    • Valor: o segredo em si (o token, a senha ou a chave). Não misture prefixos de protocolo no valor, a menos que a API de destino realmente exija o texto completo.
  5. Salve.

Na listagem aparece o nome. O valor fica protegido (não trate essa tela como bloco de notas público: só quem tem permissão de Secrets deve acessá-la).

Para trocar a chave depois: abra o mesmo Secret, atualize Valor, salve. A próxima execução da função já lê o valor novo. Não é preciso alterar o código.

2. Usar o Secret em qualquer função

keyManager está disponível no código da função (engine functions-node-v3). O argumento é o Nome cadastrado, não o valor:

module.exports = async (req, comunicationService) => {
  const secretRaw = await keyManager('api-parceiro-token');
  const secret = typeof secretRaw === 'string'
    ? secretRaw
    : (secretRaw && (secretRaw.value || secretRaw.secret || secretRaw.token));

  if (!secret) {
    throw new Error('Secret api-parceiro-token nao encontrado ou vazio');
  }

  // use `secret` na chamada HTTP, comparação, etc. — nunca em console.log
};

Regras práticas:

  • O argumento de keyManager é o Nome do cadastro, não o valor.
  • Não faça console.log do secret nem de cabeçalhos/corpos que o contenham.
  • Se o nome não existir, a leitura falha (Get secret failed nos logs de depuração). Confira o nome digitado.

O log de depuração pode mostrar que a função pediu um secret pelo nome. Isso é esperado. O valor não deve aparecer no log.

O mesmo cadastro pode ser lido por várias funções. O que muda de um caso para outro é como o script usa o valor (enviar para uma API, comparar uma senha, montar um header, etc.) — não a forma de cadastrar o Secret.

Resumo

Faça Evite
Guardar credencial em Secrets Colar token no index.js
Pedir escrita em puca_functions_api_secret se o menu não aparecer Assumir que todo usuário vê Secrets
await keyManager('nome-do-secret') const token = 'abc123...'
Rotacionar só o Valor do Secret Reescrever a função a cada troca de chave
Logar só o nome do secret, se precisar console.log do valor