Secretos: claves que necesita el código de tu sitio

#Qué es un secreto

Un secreto es un valor con nombre. El valor suele ser una clave de API: la contraseña que usa un programa para hablar con otro, como la clave que te da un servicio de envío de correos. El nombre es la forma en que el código de tu sitio la pide, por ejemplo MAILING_LIST_KEY.

La parte de tu sitio que lee secretos se ejecuta en el servidor, detrás de sus rutas (direcciones bajo /api/ que ejecutan código en lugar de mostrar una página). El valor se queda ahí. No está en las páginas del sitio, no se envía a los navegadores de los visitantes y no está en el código que puedes descargar.

Una vez guardado, un valor no se puede volver a mostrar nunca, a nadie, ni siquiera a ti. El estudio solo conserva el nombre, quién lo guardó y cuándo. Guarda tu propia copia en un lugar seguro, como un gestor de contraseñas.

Solo necesitas secretos cuando el propio código de tu sitio trabaja con algo que requiere una clave. Un sitio de presentación con un formulario de contacto no necesita ninguno.

#Antes de empezar

• Publica el sitio una vez. Los secretos se guardan solo en el sitio publicado, nunca en el estudio. Hasta la primera publicación la página dice Publish the site first y no se puede añadir nada.
• Comprueba tu rol. Los Editor, Admin y Owner añaden, cambian y eliminan secretos. Los Viewer ven los nombres y cuándo se guardó cada uno.
• Elige un nombre. Letras, dígitos y guiones bajos, empezando por una letra, hasta 128 caracteres. Lo habitual es usar mayúsculas con guiones bajos. Los nombres que empiezan por BRIKS_ están reservados para el estudio.
• Ojo con los límites. Un valor puede pesar hasta 5 KB, suficiente para cualquier clave o certificado. Un proyecto admite hasta 100 secretos, incluidos los del propio estudio.

#Añadir un secreto

#Importar varios desde un archivo .env

Un archivo .env es un archivo de texto plano con líneas NAME=value, una por secreto. Los desarrolladores suelen tener uno. Si tienes uno, puedes traer todas las líneas de una vez.

#Cambiar o quitar un secreto

Los cambios llegan al sitio en vivo al instante: verás The live site has it now o, si lo eliminas, The live site no longer has it. Si tienes muchos secretos, el cuadro Search secrets encuentra uno por su nombre. La tabla muestra el Name y el Last saved de cada uno, con quién lo guardó.

Algunas filas llevan una etiqueta Managed. El estudio las define para sus propios servicios, como los correos del sitio, y aquí no se pueden cambiar ni eliminar.

#Cómo usa un secreto la compilación

El código de tu sitio lee un secreto por su nombre cada vez que se ejecuta, así que una compilación nunca necesita el valor. Cuando le pides al estudio que conecte tu sitio con otro servicio, como una lista de correo o un modelo de IA, su código lee la clave de ese servicio con un nombre claro, como MAILING_LIST_KEY. Tú añades el valor aquí, con ese nombre.

#Que te pidan una clave antes de una compilación

• Un cambio en un sitio publicado. Cuando tu petición conecta otro servicio, el estado dice Checking which keys this needs durante un momento. Si el sitio aún no tiene valor para una clave, el estudio pregunta antes de crear. La tarjeta de la conversación tiene un campo por cada clave, hasta 3 para un cambio. Pega el valor y pulsa Save and build: va directo a los Secrets del sitio, nunca a la conversación, y el cambio empieza. Pulsa Add it later para crear sin él.
• Un mensaje enviado mientras espera se suma al cambio. Las claves que ya guardaste o que decidiste añadir más tarde no se vuelven a pedir: si tu mensaje nuevo conecta otro servicio, solo se pide su clave, una vez terminada la primera tarjeta.
• Un sitio nuevo. Los secretos necesitan un sitio publicado, así que una primera compilación todavía no puede recibir una clave. Entre sus preguntas antes de construir, puede preguntarte si construir ya la conexión y añadir la clave cuando el sitio esté en vivo, o dejar esa parte fuera por ahora.
• En Telegram, la tarjeta tiene un botón por cada clave que abre Secrets en el estudio, y Build para continuar. Una clave nunca se envía por un chat.

#Necesaria para el sitio

Después de cada publicación, Briks lee qué nombres de secretos pide el propio código del sitio. Los que aún no tienen valor aparecen primero en esta página, con la etiqueta Needed by the site. Pulsa Add value en uno y se abre el formulario con su nombre ya escrito. Mientras un nombre no tenga valor, la parte del sitio que lo usa no funciona.

La respuesta a una creación o a un cambio también los nombra, por ejemplo: The site reads MAILING_LIST_KEY, which has no value yet: add it in Project Settings → Secrets. Cada nombre tiene su propio botón, como Add MAILING_LIST_KEY, que abre esta página con el nombre ya escrito. La misma frase llega en la notificación y en Telegram cuando te avisa de que terminó una creación.

#Una clave pegada en un mensaje

Briks reconoce las formas habituales de las claves y los tokens de servicios. Una clave pegada en el chat del estudio, en la descripción de un proyecto nuevo, en el brief de un proyecto, en un mensaje a un agente o en sus instrucciones, en Ask AI del Visual Editor o en un chat con el bot se elimina antes de guardar o leer el mensaje, y se sustituye por [key removed: add it in Settings → Secrets]. El estudio lo avisa al instante: A key was removed from your message so it isn't stored. Add it in Project Settings → Secrets. La respuesta incluye un botón Open Secrets que lleva a esta página. En el hilo de un agente que trabaja en todos los proyectos, Open Secrets muestra la lista de tus proyectos para que elijas aquel al que pertenece la clave. Si algo que un agente debe recordar contiene una clave, se rechaza.

Antes de publicar un sitio, Briks lee su propio código en busca de claves escritas en los archivos: valores que parecen claves por su forma y valores asignados a cualquier cosa con nombre de clave, token o contraseña. Si encuentra alguno, la compilación se devuelve para quitar el valor y leer el secreto por su nombre.

#Seguridad que Briks aplica

• Los valores van directamente al lado del servidor del sitio publicado, cifrados. El estudio nunca los guarda, nunca los vuelve a mostrar y nunca los escribe en sus registros.
• Los valores nunca aparecen en las páginas del sitio, en los navegadores de los visitantes ni en el código que descargas.
• Solo los Editors, Admins y Owners pueden añadir, cambiar o eliminar secretos.
• Los nombres que empiezan por BRIKS_ pertenecen al estudio, y los secretos gestionados no se pueden cambiar.
• Un proyecto puede hacer hasta 60 cambios en sus secretos por minuto. Pasado ese límite verás: That is a lot of changes at once. Wait a minute and try again.

#Cuando falta un secreto

Los secretos pertenecen a la dirección del sitio. Si cambias la dirección (consulta La dirección de tu sitio), tus secretos se quedan con la antigua. El mensaje del estudio los enumera y te pide que los introduzcas de nuevo en Settings, Secrets, y cada fila muestra Not on the site · enter again. Elige Edit value en cada uno y pega su valor.

Si el código del sitio pide un secreto que no está, esa parte del sitio responde: Part of this site is not set up yet. Comprueba que el nombre coincide exactamente, mayúsculas incluidas, y que la fila no dice Not on the site.

#Ejemplo práctico: sustituir una clave filtrada

Solo entonces borraron la clave antigua en el servicio de correo, así que el sitio nunca se quedó sin una clave que funcionara. No hubo que reconstruir nada, porque el código pide la clave por su nombre.