Secrets são credenciais seguras que ficam armazenadas de forma criptografada no Botmaker e são injetadas automaticamente nas requisições HTTP das suas Code Actions. Use-os para proteger dados sensíveis como API keys, tokens de acesso ou credenciais OAuth, sem precisar escrevê-los diretamente no código. Quando uma Code Action faz uma requisição a uma URL que corresponde ao domínio configurado em um Secret, o Botmaker adiciona automaticamente os dados do Secret a essa requisição.

Você pode:

• Criar, editar e excluir Secrets.
• Definir uma ou mais rotas base (domínios) às quais cada Secret se aplica.
• Escolher como a credencial é enviada na requisição: como header, query parameter, form data ou body JSON.
• Deixar que o Botmaker injete as credenciais de forma transparente, sem expô-las no seu código.

Pré-requisitos

Acesso à sua conta do Botmaker com a permissão Ver secrets habilitada dentro do módulo Código. Sem essa permissão, o botão de Secrets não aparece.

Ao menos uma Code Action onde você vá usar as credenciais.

Para criar, editar ou excluir Secrets você também precisará das permissões correspondentes (veja a seção Permissões necessárias no final do artigo).

Conceitos-chave

Secret: conjunto de credenciais criptografadas associadas a um ou mais domínios.

Rota base: domínio ou rota base das URLs às quais o Secret se aplica (por exemplo, api.stripe.com ou api.example.com/v1). Um mesmo Secret pode ter mais de uma.

Tipo de conteúdo: define como a credencial é enviada na requisição HTTPS (Headers, Query Parameters, Body — Form Data ou Body — JSON). Não pode ser alterado depois que o Secret é criado.

Par chave-valor: cada dado individual que compõe a credencial, formado por um campo Key e um campo Value.

Injeção automática: o processo pelo qual o Botmaker detecta que uma requisição corresponde à rota base de um Secret e adiciona suas credenciais à requisição em trânsito.

bmSecret: parâmetro que você adiciona à chamada rp() na sua Code Action para indicar ao Botmaker que injete as credenciais correspondentes.

Como criar e gerenciar seus Secrets

Passo 1: Acesse o gerenciador de Secrets

Na seção de Code Actions, clique no botão Secrets para abrir o gerenciador de credenciais seguras. Ao abri-lo, você verá a lista de todos os Secrets criados na sua conta, ordenados do mais recente ao mais antigo. Para cada um são exibidos sua Descrição (nome identificador), sua Rota base (domínio ou rota à qual se aplica; pode haver mais de uma) e a data da Última modificação.

Passo 2: Crie um novo Secret

Clique em Criar Secret para abrir o formulário de criação e preencha os campos.

• Descrição (obrigatório): o nome que identifica o Secret. Use um nome claro que indique qual credencial ele representa, por exemplo Stripe API Key ou OAuth Token CRM.
• Rota base (obrigatório, uma ou mais): domínio ou rota base das URLs às quais este Secret será aplicado. Você pode adicionar mais de uma com o botão Adicionar Rota Base.
• Tipo de conteúdo (obrigatório): selecione como o Secret deve ser enviado na requisição (veja a tabela abaixo).

Tenha em mente estas regras para a rota base:

• Deve ser um domínio válido. Não são permitidos espaços nem query parameters (?).
• Não pode se sobrepor à rota base de outro Secret existente. Por exemplo, se já existe um Secret para api.example.com, você não poderá criar outro para api.example.com/v1, nem o contrário.

Boa prática: mantenha as rotas o mais específicas possível. Se você for usar um mesmo Secret para várias rotas que compartilham a base, configure uma única rota base mais geral. Por exemplo, para os endpoints https://www.rota-base.com/specific1, /specific2 e /specific3: se cada um usa um Secret diferente, configure uma rota específica por endpoint; se os três compartilham o mesmo Secret, configure uma única rota base https://www.rota-base.com/ e ela se aplicará aos três.

Dependendo do Tipo de conteúdo que você escolher, a credencial é enviada de uma forma diferente:

Para os tipos Headers, Query Parameters e Form Data, preencha os campos Key e Value de cada dado que você quer incluir. Você pode adicionar vários pares com o botão Adicionar. Para o tipo Body — JSON, insira um objeto JSON válido (valores vazios não são aceitos).

Clique em Criar secret para salvar. O botão só é habilitado quando todos os campos obrigatórios estão preenchidos e são válidos. Para descartar as alterações sem salvar, clique em Descartar ou na seta Voltar.

Nota: depois que o Secret é salvo, o Tipo de conteúdo não pode ser alterado.

Passo 3: Edite um Secret

Clique no ícone de editar na linha do Secret que você quer modificar. Você pode editar a descrição, as rotas base (adicionar novas ou remover as existentes) e os valores dos pares chave-valor. Os valores já salvos aparecem mascarados: você pode adicionar novos pares e sobrescrever os existentes, mas os pares originais não podem ser excluídos. O Tipo de conteúdo não pode ser modificado.

Passo 4: Exclua um Secret

Clique no ícone de excluir na linha do Secret. Será exibida uma caixa de diálogo de confirmação mostrando o nome do Secret e o aviso de que esta ação não pode ser desfeita. Confirme para excluí-lo permanentemente.

Como funciona a injeção automática

Os Secrets não são escritos no seu código: o Botmaker os insere na requisição no momento de executá-la. Para ativar isso, adicione o parâmetro bmSecret: true à chamada rp() da sua Code Action. Com isso você indica ao Botmaker que injete as credenciais correspondentes.

Ao executar a requisição, o Botmaker:

1. Compara a URL da requisição com as rotas base de todos os Secrets configurados.
2. Se a URL corresponde à rota base de um Secret, injeta suas credenciais como header, query param, form data ou campo do body JSON, conforme o tipo configurado.
3. Insere as credenciais de forma transparente: seu código não precisa incluí-las.

Exemplo 1 — a requisição já envia um body

Suponha que você tem um Secret do tipo Body — JSON com rota base https://botmaker-secrets.requestcatcher.com. Se o valor não existe, ele é inserido; se existe, é substituído.

Código na Code Action (o que você escreve):

function generateAccessToken() {
  return rp({
    uri: 'https://botmaker-secrets.requestcatcher.com',
    method: 'POST',
    bmSecret: true,
    body: {
      "client id": "uuID"
    },
    json: true,
  }).then(response => {
    return response.access_token;
  });
}

Requisição final enviada ao serviço (após a injeção do Botmaker):

{
  uri: 'https://botmaker-secrets.requestcatcher.com',
  method: 'POST',
  body: {
    "client id": "uuID",
    "client secrets": "<valor inyectado desde el Secret>"
  },
  json: true,
}

Exemplo 2 — a requisição não envia um body

Suponha o mesmo Secret do tipo Body — JSON e rota base https://botmaker-secrets.requestcatcher.com, mas desta vez o rp() não envia um body. O Botmaker insere o body com a credencial.

Código na Code Action (o que você escreve):

function generateAccessToken() {
  return rp({
    uri: 'https://botmaker-secrets.requestcatcher.com',
    method: 'POST',
    bmSecret: true,
    json: true,
  }).then(response => {
    return response.access_token;
  });
}

Requisição final enviada ao serviço (após a injeção do Botmaker):

{
  uri: 'https://botmaker-secrets.requestcatcher.com',
  method: 'POST',
  body: {
    "hidden_body": "<valor inyectado desde el Secret>"
  },
  json: true,
}

Nota: seu código nunca vê o valor do Secret — o Botmaker o adiciona à requisição em trânsito conforme o tipo configurado (header, query param, form data ou campo do body JSON). Também não registramos logs das requisições que usam Secrets.

Erros comuns

Permissões necessárias

As permissões para gerenciar Secrets são configuradas dentro do módulo Código ao editar uma função (role). Com qualquer uma das três o botão de Secrets fica visível; cada uma habilita uma funcionalidade diferente:

Um usuário com as três permissões tem acesso completo ao gerenciador de Secrets.

Lembre-se de visitar nossa Central de Ajuda para obter mais informações.