Secrets son credenciales seguras que se guardan de forma cifrada en Botmaker y se inyectan automáticamente en las solicitudes HTTP de tus Code Actions. Los usás para proteger datos sensibles como API keys, tokens de acceso o credenciales OAuth, sin necesidad de escribirlos directamente en el código. Cuando una Code Action hace una solicitud a una URL que coincide con el dominio configurado en un Secret, Botmaker agrega automáticamente los datos del Secret a esa solicitud.

Puedes:

• Crear, editar y eliminar Secrets.
• Definir una o más rutas base (dominios) a las que se aplica cada Secret.
• Elegir cómo se envía la credencial en la solicitud: como header, query parameter, form data o body JSON.
• Dejar que Botmaker inyecte las credenciales de forma transparente, sin exponerlas en tu código.

Requisitos previos

Acceso a tu cuenta de Botmaker con el permiso Ver secrets habilitado dentro del módulo Código. Sin este permiso, el botón de Secrets no aparece.

Al menos una Code Action donde vayas a usar las credenciales.

Para crear, editar o eliminar Secrets necesitarás además los permisos correspondientes (ver la sección Permisos requeridos al final del artículo).

Conceptos clave

Secret: conjunto de credenciales cifradas asociadas a uno o más dominios.

Ruta base: dominio o ruta base de las URLs a las que se aplica el Secret (por ejemplo, api.stripe.com o api.example.com/v1). Un mismo Secret puede tener más de una.

Tipo de contenido: define cómo se envía la credencial en la solicitud HTTPS (Headers, Query Parameters, Body — Form Data o Body — JSON). No se puede cambiar una vez creado el Secret.

Par clave-valor: cada dato individual que compone la credencial, formado por un campo Key y un campo Value.

Inyección automática: el proceso por el cual Botmaker detecta que una solicitud coincide con la ruta base de un Secret y agrega sus credenciales al request en tránsito.

bmSecret: parámetro que agregás al llamado rp() en tu Code Action para indicarle a Botmaker que inyecte las credenciales correspondientes.

Cómo crear y gestionar tus Secrets

Paso 1: Accede al administrador de Secrets

Desde la sección de Code Actions, haz clic en el botón Secrets para abrir el administrador de credenciales seguras. Al abrirlo verás la lista de todos los Secrets creados en tu cuenta, ordenados del más reciente al más antiguo. Para cada uno se muestra su Descripción (nombre identificatorio), su Ruta base (dominio o ruta al que se aplica, puede haber más de una) y la fecha de Última modificación.

Paso 2: Crea un nuevo Secret

Haz clic en Crear Secret para abrir el formulario de creación y completa los campos.

• Descripción (requerido): nombre que identifica al Secret. Usa un nombre claro que indique qué credencial representa, por ejemplo Stripe API Key u OAuth Token CRM.
• Ruta base (requerido, una o más): dominio o ruta base de las URLs a las que se aplicará el Secret. Puedes agregar más de una con el botón Agregar Ruta Base.
• Tipo de contenido (requerido): selecciona cómo debe enviarse el Secret en la solicitud (ver la tabla más abajo).

Ten en cuenta estas reglas para la ruta base:

• Debe ser un dominio válido. No se permiten espacios ni query parameters (?).
• No puede superponerse con la ruta base de otro Secret existente. Por ejemplo, si ya existe un Secret para api.example.com, no podrás crear otro para api.example.com/v1, ni al revés.

Buena práctica: mantén las rutas lo más específicas posible. Si vas a usar un mismo Secret para varias rutas que comparten base, configura una sola ruta base más general. Por ejemplo, para los endpoints https://www.ruta-base.com/specific1, /specific2 y /specific3: si cada uno usa un Secret distinto, configura una ruta específica por endpoint; si los tres comparten el mismo Secret, configura una única ruta base https://www.ruta-base.com/ y se aplicará a los tres.

Según el Tipo de contenido que elijas, la credencial se envía de una forma distinta:

Para los tipos Headers, Query Parameters y Form Data, completa los campos Key y Value de cada dato que quieras incluir. Puedes agregar múltiples pares con el botón Agregar. Para el tipo Body — JSON, ingresa un objeto JSON válido (no se aceptan valores vacíos).

Haz clic en Crear secret para guardar. El botón solo se habilita cuando todos los campos requeridos están completos y son válidos. Para descartar los cambios sin guardar, haz clic en Descartar o en la flecha de Volver.

Nota: una vez guardado el Secret, no es posible cambiar el Tipo de contenido.

Paso 3: Edita un Secret

Haz clic en el ícono de editar en la fila del Secret que quieras modificar. Puedes editar la descripción, las rutas base (agregar nuevas o eliminar las existentes) y los valores de los pares clave-valor. Los valores ya guardados aparecen enmascarados: puedes agregar nuevos pares y sobrescribir los existentes, pero los pares originales no pueden eliminarse. El Tipo de contenido no puede modificarse.

Paso 4: Elimina un Secret

Haz clic en el ícono de eliminar en la fila del Secret. Se mostrará un diálogo de confirmación con el nombre del Secret y el aviso de que esta acción no puede deshacerse. Confirma para eliminarlo de forma permanente.

Cómo funciona la inyección automática

Los Secrets no se escriben en tu código: Botmaker los inserta en la solicitud en el momento de ejecutarla. Para activarlo, en el llamado a rp() de tu Code Action agrega el parámetro bmSecret: true. Con eso le indicás a Botmaker que inyecte las credenciales correspondientes.

Al ejecutar el request, Botmaker:

1. Compara la URL del request con las rutas base de todos los Secrets configurados.
2. Si la URL coincide con la ruta base de un Secret, inyecta sus credenciales como header, query param, form data o campo del body JSON, según el tipo configurado.
3. Inserta las credenciales de forma transparente: tu código no necesita incluirlas.

Ejemplo 1 — el request ya envía un body

Supón que tienes un Secret de tipo Body — JSON con ruta base https://botmaker-secrets.requestcatcher.com. Si el valor no existe se inserta; si existe, se reemplaza.

Código en la Code Action (lo que escribís):

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;
  });
}		

Request final enviado al servicio (después de la inyección de Botmaker):

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

Ejemplo 2 — el request no envía un body

Supón el mismo Secret de tipo Body — JSON y ruta base https://botmaker-secrets.requestcatcher.com, pero esta vez el rp() no envía un body. Botmaker inserta el body con la credencial.

Código en la Code Action (lo que escribís):

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

Request final enviado al servicio (después de la inyección de Botmaker):

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

Nota: tu código nunca ve el valor del Secret — Botmaker lo agrega al request en tránsito según el tipo configurado (header, query param, form data o campo del body JSON). Tampoco se registran logs de los request que usan Secrets.

Errores comunes

Permisos requeridos

Los permisos para gestionar Secrets se configuran dentro del módulo Código al editar un rol. Con cualquiera de los tres el botón de Secrets queda visible; cada uno habilita una funcionalidad distinta:

Un usuario con los tres permisos tiene acceso completo al administrador de Secrets.

Recuerda visitar nuestro Centro de Ayuda para mayor información