[Vibe Coder #2] ¿Qué es una API y por qué hay que ocultar las claves de API?

En la primera parte comparé una app con un restaurante: comedor (frontend), cocina (backend) y almacén (DB). Esta vez tratamos el tema que más problemas causa al hacer vibe coding: las API y las claves de API. Todos han visto alguna vez la advertencia «No expongas nunca tu clave», pero rara vez se explica qué es, dónde está y qué ocurre si queda expuesta. Aquí lo dejamos claro de una vez.

Una API es un mostrador de pedidos

API significa Application Programming Interface, pero puedes olvidar el nombre completo. Lo importante es esto. Una API es el mostrador donde los programas encargan trabajo a otros programas.

Volvamos a la analogía del restaurante: los clientes no pueden entrar en la cocina. En su lugar, entregan un pedido con un formato establecido: «Una sopa de kimchi, poco picante». La cocina lo prepara y lo entrega. Una API es exactamente ese mostrador. Envías una solicitud con el formato establecido a la dirección establecida y recibes una respuesta con el formato establecido.

Las apps de los vibe coders tienen API en dos direcciones.

• La API de mi app: el mostrador que usa mi frontend para encargar trabajo a mi backend. La app/api/ carpeta de la primera parte es precisamente esto.
• La API de terceros: el mostrador que usa mi app para encargar trabajo al servicio de otra empresa. Pedir a ChatGPT que escriba un texto (OpenAI API), mostrar un mapa (API de mapas) o procesar pagos (API de pagos) consiste en hacer pedidos en el mostrador de otra empresa.

La mayoría de las apps creadas mediante vibe coding funcionan combinando estas «API de terceros». Y para hacer un pedido en el mostrador de otra empresa hace falta algo imprescindible.

Una clave de API es una tarjeta corporativa

Las API de terceros no son mostradores gratuitos. Cada solicitud a OpenAI genera un coste. Por eso cada solicitud lleva una identificación que indica «¿a quién se factura este pedido?». Esa es la clave de API, una cadena larga y aleatoria como sk-proj-....

Una clave de API se comporta exactamente como una tarjeta corporativa.

• La use quien la use, la factura llega al titular de la tarjeta.
• Basta con conocer el número de la tarjeta para usarla. No hay verificación facial ni de firma.
• Por eso, si dejas el número de la tarjeta en un lugar público, cualquiera en el mundo puede pagar con mi dinero.

Esta es la razón por la que la advertencia «oculta la clave» es tan grave. Exponer una clave no es lo mismo que exponer una contraseña. Una contraseña se cambia y listo, pero todos los cargos realizados desde el robo de la clave hasta su revocación se acumulan en mi factura.

Qué ocurre realmente cuando se expone

Es fácil pensar: «¿Quién va a encontrar la clave de mi pequeña app?». Ese es el error de percepción más peligroso. Quienes encuentran las claves no son personas, sino bots.

Repositorios públicos como GitHub reciben el rastreo continuo de miles de bots. Si subes por error código que contiene una clave a un repositorio público, normalmente un bot la recopila en unos minutos. Las claves recopiladas se usan de inmediato para llamadas gratuitas a la IA, pagos de minería de criptomonedas, envío de spam y actividades similares. Por eso la comunidad sigue publicando casos de facturas de millones de wones acumuladas de la noche a la mañana.

Otra vía de exposición es la que vimos en la primera parte: poner la clave en el frontend. Como el código del frontend se envía al navegador del usuario, cualquiera puede extraer la clave con un clic derecho y «Inspeccionar». Cuando pides a la IA «integra OpenAI», puede insertar la clave directamente en el frontend por comodidad, así que debes comprobarlo personalmente.

Dónde debe estar la clave

El principio ya apareció en la primera parte: los secretos van en el backend. En concreto:

• Escribe la clave en el archivo .env del proyecto. Es un almacén de valores secretos que solo lee el backend.
• Registra el archivo .env en .gitignore para que Git no lo siga. Así, aunque subas el código a GitHub, la clave solo permanece en tu ordenador. Los proyectos generados por IA normalmente ya lo incluyen, pero merece la pena comprobarlo una vez.
• Una app desplegada no puede leer el .env de tu ordenador, así que debes registrar la clave por separado en el menú «Environment Variables» del panel del servicio de despliegue, como Vercel. Volveremos a este tema en la parte 4 (despliegue).

Next.js tiene otra trampa. Si el nombre de una variable de entorno empieza por NEXT_PUBLIC_, su valor también se envía al frontend. Como indica el nombre, se hace público. Coloca aquí solo claves diseñadas para exponerse, como las de mostrar mapas; nunca añadas NEXT_PUBLIC_ a claves con coste, como las de OpenAI. Si la IA lo ha añadido, es una señal de peligro por sí sola.

Cómo revisar tu app por tu cuenta

Estas son tres comprobaciones que puedes hacer ahora mismo.

1. Inspección del navegador: En tu sitio desplegado, haz clic derecho → Inspeccionar y busca términos como sk-, key y secret en las pestañas Network o Sources. Si aparece tu clave secreta, está expuesta.
2. Inspección de GitHub: Si tu repositorio es público (Public), busca el comienzo de la clave en el buscador del repositorio. También está expuesta si solo aparece en un commit antiguo.
3. Pide una auditoría a la IA: Dile «Busca todos los lugares de este proyecto donde una clave de API o un valor secreto se envíe al frontend». La IA que cometió un error al crearlo también puede encontrarlo bien.

Si ya se ha expuesto

Ocultar una clave expuesta no sirve de nada. Debes asumir que un bot ya la ha copiado. El orden es el siguiente.

1. En el panel del servicio, elimina (revoca) esa clave. El uso indebido se detiene desde ese momento.
2. Emite una clave nueva y esta vez añádela solo a .env y al panel de despliegue.
3. Configura el límite de uso (spending limit) del servicio. Será el tope de daños en el próximo incidente. Lo explicamos con detalle en la parte 7 (facturas desorbitadas).

Resumen

• Una API es un mostrador de pedidos entre programas, y mi app funciona combinando API de terceros.
• Una clave de API es una tarjeta corporativa. La use quien la use, la factura me llega a mí.
• Los bots encuentran las claves en cuestión de minutos. «Mi app es pequeña» no sirve como defensa.
• La clave solo debe estar en dos lugares: .env(localmente) y las variables de entorno del panel de despliegue. Una clave con coste que incluya NEXT_PUBLIC_ es una señal de peligro.
• Si queda expuesta, no la ocultes: revoca → vuelve a emitir → establece un límite.

La próxima parte trata sobre Git. Veremos por qué todos recomiendan usar Git aunque la IA escriba todo el código y cómo volver en un minuto al estado anterior cuando la IA rompe una app que funcionaba.