Ocultar una clave API: muévela a una Edge Function de Supabase

Todas las guías sobre una clave API filtrada acaban en el mismo sitio: muévela a un servidor. Y ahí se paran. Te quedas con una app que construiste en Lovable, Bolt o Cursor, ningún servidor a la vista, y una frase que da por hecho que ya sabes qué hacer a continuación.

Esto es lo que guía tras guía deja fuera. Mover la clave a una Edge Function de Supabase la saca de tu página, y por sí solo eso no impide que un desconocido la use. La propia documentación de Supabase dice por qué: la comprobación que una function desplegada ejecuta por defecto acepta también tu clave pública, y tu clave pública está en tu frontend, al alcance de cualquiera que quiera copiarla. Ocultar la clave es la mitad sencilla. De la otra mitad no escribe nadie: decidir a quién responde tu function nueva.

Piensa en la clave como la llave maestra de un almacén. Ahora mismo está pegada por dentro del escaparate, donde la lee cualquiera que se pare. Una Edge Function es una trastienda con ventanilla: la llave entra ahí, y los visitantes preguntan por la ventanilla en vez de pasar y servirse. Que eso sea una mejora depende de a quién se le abre la ventanilla.

¿Dónde pongo mi clave API si no es en el frontend?

En cualquier sitio que no sea el navegador. Una Edge Function es la versión más pequeña de eso.

Un navegador no sabe guardar un secreto. Todo lo que tu página necesita para funcionar lo descarga cada visitante, y un visitante puede leerlo todo: el código, las imágenes, los valores compilados dentro del código. Eso no es un fallo de tu herramienta. Es lo que es una página web. Qué claves API son seguras en tu frontend es la versión larga; la corta es que una clave sk_, una clave de OpenAI o una clave secreta de Supabase nunca iba a sobrevivir a un viaje al navegador.

Una Edge Function de Supabase es un trozo pequeño de código que se ejecuta en las máquinas de Supabase. Puede leer los secretos que hayas puesto en tu proyecto, responde en una dirección web propia, y tu app la llama por su nombre. Escribes un archivo, Supabase lo ejecuta, y no hay servidor que alquilar, parchear ni mantener despierto.

Sustituye la clave que ya publicaste, antes de mover nada

La clave que hoy está en tu frontend ya es pública, y lo sigue siendo después de que la saques del código.

Cada visitante que cargó tu sitio la descargó. Cada rastreador también, y los hay automáticos recorriendo toda la web en busca exactamente de estas cadenas. Tu bundle antiguo sigue además en tu historial de versiones y en cualquier caché que tenga una copia de tu página. Borrar una línea de un archivo que controlas no cambia nada sobre un valor que ya se ha repartido.

Así que el orden es: crear una clave nueva en el proveedor, guardarla un momento, y revocar la antigua en cuanto la function de abajo esté en marcha. Lee después tu página de facturación y tus registros de uso de todo el periodo en que la clave antigua estuvo fuera. Sustituirla detiene lo que viene; no tiene ningún efecto sobre lo que ya pasó. Si la clave era una clave secreta de Supabase, el orden en que trabajar tiene un matiz que conviene leer antes.

Los cuatro pasos

Guardar el secreto, escribir la function, desplegarla, y cambiar tu app para que llame a la function en vez de al proveedor.

Dentro de la function el secreto llega como variable de entorno, es decir, un valor con nombre que el código puede leer y nadie de fuera. La documentación de Supabase sobre secretos de Edge Functions tiene la referencia completa, y tres detalles de ahí ahorran una hora de confusión:

• El nombre de un secreto no puede empezar por SUPABASE_. Ese prefijo está reservado para los valores que Supabase pone por ti, y lo rechazan tanto el panel como la API.
• Un secreto nuevo se lee de inmediato. No hay que volver a desplegar la function después de cambiar uno.
• Local y producción van por separado. La pila local lee supabase/functions/.env, que es un sitio distinto de los secretos de tu proyecto en marcha, así que pon el valor en ambos o la function funcionará en tu máquina y fallará una vez desplegada.

Borra después la variable antigua de tu frontend. Si se llamaba VITE_, NEXT_PUBLIC_ o EXPO_PUBLIC_, ese prefijo era la instrucción de compilar el valor dentro del bundle, y el prefijo es toda la historia de cómo llegó ahí.

¿Exigir un token significa que solo llaman mis usuarios?

No, y este es el punto del artículo que merece dos lecturas.

Supabase activa por defecto una comprobación llamada verify_jwt. Mira la cabecera Authorization antes de que corra tu código y rechaza la petición si ahí no hay nada válido. Suena a puerta que solo abren tus usuarios. No lo es, porque Supabase documenta además que la misma comprobación acepta una clave pública o secreta en cualquiera de las dos cabeceras, por compatibilidad con proyectos antiguos, y añade con claridad que la comprobación por sí sola no autentica a quien llama enviando únicamente una clave API.

Tu clave pública está en tu frontend. Eso es correcto y está pensado así. También significa que quien abra tu sitio, lea la clave y se la envíe a tu function nueva pasa la comprobación de la plataforma y entra en tu código.

En el almacén, verify_jwt es un portero que comprueba que llevas una acreditación de visitante. La lleva cada visitante, porque las repartes tú en la puerta. Quien está en la ventanilla hace otro trabajo, y es quien pregunta qué visitante eres.

Cerrar la function, para no haber montado un proxy abierto

Decide a qué llamantes acepta tu function, y escribe esa decisión dentro de la function.

Supabase trae un envoltorio para esto, así que es una línea y no un proyecto. Pon auth: 'user' y la function acepta el token de un usuario con sesión iniciada y le da a tu código un cliente de base de datos ya limitado a las reglas de Row Level Security de ese usuario:

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    // ctx.userClaims dice quién llama. Rechaza aquí lo que no quieras,
    // y luego llama al proveedor con el secreto del entorno.
    return Response.json({ ok: true })
  }),
}

La página Securing Edge Functions enumera los demás modos, y dos de ellos importan en una app corriente. Una function a la que llama otra máquina y no un navegador usa auth: 'secret', con la clave secreta enviada en la cabecera apikey. Una function que recibe webhooks de Stripe o de GitHub no puede usar ninguno de los dos, porque esos proveedores no tienen ningún token tuyo; pone verify_jwt = false y comprueba la firma del proveedor dentro del handler.

Elijas lo que elijas, decide a conciencia qué pasa cuando aparece un llamante con el que no contabas. El ejemplo que da Supabase de una function que puede aceptar a cualquiera es una comprobación de estado, y una comprobación de estado no cuesta nada cuando la llama un desconocido. Una function que reenvía una llamada de API de pago te factura cada una.

¿Puedo usar service_role en una Edge Function?

Sí. Una function es el único sitio donde una clave secreta de Supabase tiene cabida.

Tampoco tienes que pegarla. Supabase pone las claves del proyecto en el entorno de la function, así que el código las lee de ahí y no de un secreto que hayas puesto tú. Los proyectos nuevos reciben SUPABASE_SECRET_KEYS y SUPABASE_PUBLISHABLE_KEYS, cada uno un pequeño diccionario de claves con nombre; los proyectos más antiguos reciben SUPABASE_SERVICE_ROLE_KEY y SUPABASE_ANON_KEY con sus nombres de siempre. Qué cambió cuando Supabase renombró sus claves te dice qué par tienes.

Usa la clave secreta para el trabajo que de verdad tiene que ver cada fila, como escribir un registro de auditoría que el usuario no pueda editar. Para todo lo que un usuario lee sobre sí mismo, usa su propio token y deja que filtren tus reglas de Row Level Security, que para eso están.

Comprobarlo desde el navegador, la única prueba real

Carga tu sitio en marcha, abre la pestaña de red, y mira qué envía de verdad tu navegador.

Las dos cosas a comprobar:

• Ninguna petición lleva la clave. Recorre la parte de tu app que antes llamaba al proveedor. La petición saliente debe ir a …supabase.co/functions/v1/tu-function, y la única credencial que haya dentro debe ser tu clave pública o el token de tu usuario.
• La clave no está en el código descargado. Usa la búsqueda de tu navegador en todos los archivos cargados y pega la primera docena de caracteres de la clave antigua. Ningún resultado es la respuesta que quieres.

Solo una reconstrucción y un nuevo despliegue sacan un valor del bundle. Una clave que sigue apareciendo en la búsqueda suele significar que el frontend salió antes de que saliera la variable.

Nuestro escaneo gratuito hace la segunda comprobación desde fuera y nombra lo que puede leer en tu bundle en marcha, incluida qué clave de Supabase has publicado. Tarda unos 20 segundos y no necesita cuenta: escanea tu app.

Cómo hacerlo desde Lovable, Bolt o Replit

Usa el panel de Supabase. Ahí no hay ningún paso de terminal.

Abre tu proyecto, elige Edge Functions en la barra lateral y luego Deploy a new function → Via Editor. La guía rápida del panel de Supabase lo recorre con capturas, y entre las plantillas que ofrece hay una para reenviar a un proveedor de IA, que es exactamente la forma de este trabajo. El despliegue tarda entre diez y treinta segundos, y la function queda en marcha en una dirección propia. Tu secreto va en la página Edge Function Secrets, en la misma sección.

Una advertencia que conviene conocer antes de confiarte: Supabase escribe que el editor del panel no tiene control de versiones, ni versiones, ni vuelta atrás, y lo recomienda para trabajo rápido y no para código que vaya a quedarse. Pulsar Deploy sobrescribe lo que había. Si la function acaba haciendo algo que te importa, descárgala desde esa página y guarda el archivo.

Hay además una versión de esta pregunta con forma de Replit, porque Replit tiene su propio almacén de secretos y tu app ejecuta allí su propio servidor. Qué hacen de verdad los Replit Secrets es esa versión.

Cuándo una Edge Function es la respuesta equivocada

Dos casos, y en los dos la mudanza te cuesta trabajo y no aporta nada.

La clave era pública por diseño. Una clave pk_live_ de Stripe, una clave pública de Supabase o una clave anon, un token público de Mapbox: están hechas para vivir en un navegador, y la protección está en otro sitio. Poner una detrás de una function añade un rodeo y no quita ningún riesgo. Cuáles son esas claves es la lista.

La clave se puede restringir a tu propio sitio. Las claves de navegador de Google son el ejemplo habitual: en la consola de Google puedes limitar una a tus dominios, y esa es justo la solución que Google prevé para este caso. La clave sigue siendo legible y deja de servirle a quien la copie.

Todo lo demás va en un servidor. Una clave de OpenAI o de Anthropic no tiene variante pública, y por eso una clave de proveedor de IA en tu frontend no tiene ningún ajuste que la salve, y ninguna minificación esconde una clave secreta de Stripe de quien lea tu página.

Qué hacer ahora mismo

Si prefieres repasar tu app entera en vez de una sola clave, la checklist de seguridad en 10 minutos cubre esto junto a las otras cosas que conviene cerrar en una app recién lanzada.