Notas de quickstart
Por qué no debes llamar a la API de cuotas desde el navegador
Una app de navegador no puede esconder una clave de API. Todo visitante puede leerla, y una clave filtrada entrega tus límites y tus streams a desconocidos.
La pregunta llega pronto en todo proyecto web: ¿puede la página pedir cuotas a la API directamente? La respuesta es no, y la razón cabe en una frase. Todo lo que tu navegador envía, cualquier visitante puede leerlo, incluida tu clave. La solución es un pequeño servidor entre la página y la API.
El navegador no guarda secretos
La API autentica con tu clave en la cabecera x-portal-apikey, o como parámetro de consulta en los endpoints de streaming, como muestran los quickstarts del sitio. De cualquier forma, la clave viaja con la solicitud. En un navegador, la solicitud está ahí en las herramientas de desarrollador de cualquiera que abra tu página: la cabecera, la URL, la clave.
Una clave suelta por el mundo no es una fuga menor. Es tu cuota de sondeo gastada por el bucle de otra persona, tu stream de alertas mantenido abierto desde una máquina que no conoces, y ninguna forma de distinguir su tráfico del tuyo en tus logs.
Lo que pasa cuando la clave se filtra
El daño es silencioso. Tus sondeos empiezan a chocar con el techo porque el script de un desconocido gasta la misma cuota. Tu stream de alertas se cierra porque una segunda conexión con tu clave expulsa la tuya. Nada en la API se comporta mal; está haciendo exactamente lo que una clave válida pide, para otra persona.
Rotar la clave solo ayuda después de que la fuga se detiene, y no se detiene hasta que la clave sale de la página.
La forma que funciona: tu servidor en el medio
El patrón que todo quickstart de este sitio ya usa es la respuesta. El quickstart de Python lee la clave de una variable de entorno en tu máquina, y nunca toca un navegador. Para una app web, la misma frontera aplica: tu página llama a tu propio backend, tu backend llama a la API con la clave, y la clave nunca sale del servidor.
Ese backend puede tener veinte líneas: un endpoint que pide el tablero, lo recorta a lo que tu página necesita, y responde desde su propia copia con su propia nota de frescura. El quickstart de curl basta para prototiparlo, porque el backend son las mismas dos llamadas, en el lado del servidor.
La excepción que no lo es
Una demo pública con una clave desechable en un nivel gratuito sigue siendo una fuga; solo filtra una cuota menor. Si no pegarías la clave en un chat público, no la pegues en una página pública. La regla es la misma en cualquier tamaño de proyecto.
El servidor guarda la clave, la página no guarda nada. Esa única frontera es todo el modelo de seguridad que esta API necesita.