Autenticación de API de mapas

Un diseño seguro de autenticación separa las credenciales según el entorno de ejecución. El navegador necesita una credencial que pueda exponerse y esté muy restringida a orígenes y capacidades aprobados. El backend necesita una credencial secreta que nunca llegue al código cliente y autorice operaciones entre servidores. No deben ser intercambiables. Limita ámbitos, separa entornos, supervisa el uso, rota credenciales y distingue los fallos de autenticación de los de autorización. Kaleidr lo implementa con claves publicables (kld_pk_live_…) y claves de servidor (kld_sk_live_…).

Las secciones siguientes tratan credenciales de navegador y servidor, orígenes, CORS, ámbitos, ciclo de vida, límites de confianza multiinquilino y errores comunes. Consulta la documentación para desarrolladores. Para la arquitectura del SDK, consulta ¿Qué es un SDK de mapas con IA?. Para inserción y montajes de chat, consulta Cómo insertar un mapa interactivo y Chat con IA en Mapbox, Google Maps y MapLibre.

Principios esenciales

• Primero el entorno: las credenciales del navegador se diseñan para exponerse; las del servidor, para mantenerse secretas.
• Origen ≠ autenticación: CORS y los orígenes permitidos no sustituyen la comprobación de credenciales.
• Ámbito ≠ inquilino: los ámbitos de capacidad no son autorización de usuario ni de filas.
• Rotación segura: despliega un reemplazo antes de revocar una clave activa.
• Censura los registros: guarda ID de clave y códigos de estado, nunca valores de credenciales.

¿Por qué es diferente la autenticación en el navegador?

El navegador es un entorno no fiable. Todo lo que recibe suele poder inspeccionarse mediante el código fuente, las herramientas de desarrollo, las solicitudes de red, JavaScript empaquetado, el almacenamiento o los objetos en ejecución. Incluir un secreto de servidor duradero en código cliente—React, variables NEXT_PUBLIC_* de Next.js, VITE_* de Vite, HTML, webviews móviles o JSON del frontend—es inseguro porque el navegador no puede ocultarlo a quien lo ejecuta. Pregunta qué puede hacer la credencial y dónde puede ejecutarse, no dónde esconderla en el paquete.

Las plataformas usan nombres diferentes, pero el patrón es común. Kaleidr usa claves publicables y de servidor (Auth & Scopes). Mapbox distingue ámbitos públicos y secretos y exige usar el servidor para tokens secretos (Cómo usar Mapbox de forma segura). Google Maps Platform emplea restricciones de aplicación y API y recomienda proteger credenciales de servicios web, con OAuth 2.0 cuando se admita entre servidores (Guía de seguridad). Las credenciales cliente deben diseñarse para exponerse; las del servidor, para mantenerse secretas.

¿Cómo funcionan las claves publicables y de servidor de Kaleidr?

La documentación actual define dos formas dentro del mismo sistema de organización y capacidades. Las claves publicables usan el prefijo kld_pk_live_… en HTML, el SDK, <kaleidr-map> e integraciones web. El SDK las intercambia por una sesión breve vinculada al origen, en vez de usar la cadena como credencial bearer permanente. Las claves de servidor usan kld_sk_live_… solo en servidores fiables, normalmente como Authorization: Bearer … o X-Api-Key: …. Están bloqueadas en el navegador y no reciben permiso CORS (CORS & Allowed Origins). Nunca pongas una clave de servidor en el cliente ni trates una variable pública del frontend como almacén secreto.

Los orígenes permitidos deben ser orígenes puros, sin ruta ni barra final: https://app.example.com, no https://app.example.com/maps. Kaleidr exige HTTPS salvo pruebas locales en localhost o 127.0.0.1. La coincidencia exacta importa: los hosts raíz, www, app, admin y vista previa son orígenes distintos. Estas restricciones reducen la reutilización no autorizada, pero no sustituyen mantener los secretos fuera del cliente.

¿En qué se diferencian CORS, autenticación, ámbito y autorización?

CORS controla si el navegador puede leer una respuesta entre orígenes. La autenticación identifica al solicitante. La autorización por ámbito decide si la credencial puede usar una capacidad. La autorización de la aplicación anfitriona decide qué usuario o inquilino accede a registros privados. Kaleidr puede permitir una solicitud previa, pero solo devuelve Access-Control-Allow-Origin si el origen está autorizado; las claves de servidor no reciben permiso CORS. Un 401 suele indicar credencial ausente, inválida, caducada o revocada. Un 403 suele indicar credencial válida sin permiso; Kaleidr usa insufficient_scope cuando falta la capacidad de la ruta. Trátalos como fallos distintos en diagnóstico y supervisión.

¿Cómo crear, guardar, rotar y revocar credenciales?

Aplica privilegio mínimo: concede solo los ámbitos necesarios. Mapbox recomienda ámbitos mínimos y únicamente públicos en el navegador; Google recomienda restricciones de aplicación y API limitadas a las APIs usadas. No compartas una credencial entre desarrollo, vista previa y producción: sepáralas para reducir el radio de impacto y facilitar la rotación. Mapbox recomienda tokens distintos por entorno o cliente; Google, claves separadas por aplicación (Gestión de tokens).

Los valores de claves Kaleidr nuevas se muestran una sola vez; cópialos de inmediato en un gestor de secretos. Guarda claves de servidor en un gestor o entorno protegido, nunca en repositorios públicos ni paquetes web. En CI/CD, inyecta secretos al desplegar, ocúltalos en registros y evita imprimir volcados del entorno. Registra ID, estado y origen; censura encabezados de autorización y valores. Para rotar, crea un reemplazo, configura restricciones, despliega, verifica el tráfico y revoca la anterior; actúa más rápido si está comprometida. Las cuotas también son control de seguridad: el uso se mide por organización y los endpoints de streaming controlan concurrencia (Quota & Rate Limits). Trata 429 de forma distinta a 401 y 403; aplica espera progresiva y evita tormentas de reintentos.

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

¿Cómo separar la autenticación de plataforma y del sistema anfitrión?

El patrón recomendado mantiene en el navegador una clave publicable para funciones públicas del SDK mediante un origen aprobado, mientras que las solicitudes autenticadas van al backend. Este gestiona identidad, pertenencia al inquilino, autorización de objetos, datos privados y una clave de servidor en un gestor de secretos; llama a la plataforma entre servidores y devuelve solo campos autorizados. Las claves publicables no autentican al usuario final, y las de servidor no autorizan filas de base de datos. Según la documentación, un mapa Viewer publicado se protege mediante enlace compartido y no necesita clave; aun así, trata esos enlaces como controles de acceso y no envíes datos privados a una vista pública sin restricciones. CSP y la representación segura de HTML son controles complementarios; Mapbox advierte del riesgo XSS al insertar HTML no fiable en ventanas emergentes y recomienda representar texto.

¿Qué errores deben evitar los equipos?

Si falla el navegador, revisa la escritura del origen, HTTPS, tipo de clave, ámbito y orden de intercambio antes de asumir que la plataforma está caída. Si falla el servidor, revisa tipo, entorno, ámbito, inyección del secreto y posible revocación accidental.

Veredicto final

La seguridad empieza con una decisión: no uses el mismo modelo de credenciales en navegador y backend. El navegador necesita credenciales exponibles limitadas por origen, ámbito, duración o controles equivalentes; el backend necesita secretos en infraestructura fiable. Añade privilegio mínimo, aislamiento de entornos, autorización de aplicación, supervisión y rotación. Kaleidr sigue este patrón: las claves publicables están limitadas por origen y se intercambian por sesiones breves; las claves de servidor son credenciales bearer para llamadas entre servidores y están bloqueadas en el navegador. Esa frontera importa más que intentar ocultar una clave en el frontend.

Protege tu API de mapas con la documentación de Kaleidr

Revisa los tipos de clave, ámbitos, reglas de origen y comportamiento antes de desplegar. Lee Kaleidr Auth & Scopes y continúa en la documentación para desarrolladores para montajes del SDK y rutas de Platform API.

Preguntas frecuentes

¿Qué es la autenticación de API de mapas?

Es el mecanismo que identifica una aplicación o servicio que solicita acceso a APIs de mapas, lugares, teselas, rutas o datos espaciales. Incluye claves, tokens de acceso, sesiones, tokens bearer y OAuth.

¿Puede usarse una clave API de forma segura en el navegador?

Solo si el proveedor la diseña para el cliente. Debe tener restricciones de origen, ámbitos públicos, restricciones de app o intercambio por sesiones breves. Un secreto de servidor nunca debe aparecer en el navegador.

¿Es secreta una clave publicable?

No. Su seguridad no debe depender de ocultar la cadena, aunque necesita restricciones y supervisión.

¿Es secreta una clave de servidor?

Sí. Debe permanecer en infraestructura backend fiable y no aparecer en HTML, paquetes JavaScript, webviews, repositorios públicos ni almacenamiento cliente.

¿Es CORS autenticación?

No. CORS controla la lectura de respuestas entre orígenes; la autenticación identifica al solicitante y la autorización determina qué puede hacer.

¿Cuál es la diferencia entre 401 y 403?

401 suele significar credencial ausente, inválida, caducada o revocada. 403 suele significar credencial válida sin permiso para la operación.

¿Debo separar las claves de desarrollo y producción?

Sí. Reduce el radio de impacto, simplifica las restricciones, mejora la visibilidad y hace más segura la rotación.

¿Cómo roto una clave API?

Crea y restringe un reemplazo, despliega, verifica el tráfico y solo entonces revoca la anterior. Actúa más rápido ante un compromiso activo.

¿Kaleidr Viewer necesita una clave API?

La documentación actual indica que los mapas Viewer publicados se protegen mediante enlace compartido y no necesitan clave.

¿Cómo protege Kaleidr las integraciones web?

Usa una clave publicable con lista de orígenes. El SDK la intercambia por una sesión breve vinculada al origen. Las claves de servidor están bloqueadas en el navegador y se destinan a llamadas entre servidores.

Referencias

• IETF. HTTP Semantics (RFC 9110). RFC Editor. Consultado el 17 de agosto de 2026. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. Consultado el 17 de agosto de 2026. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. Consultado el 17 de agosto de 2026. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google. Guía de seguridad de Google Maps Platform. Documentación de Google Maps Platform. Consultado el 17 de agosto de 2026. https://developers.google.com/maps/api-security-best-practices

• Kaleidr. Auth & Scopes. Documentación para desarrolladores de Kaleidr. Consultado el 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr. CORS & Allowed Origins. Documentación para desarrolladores de Kaleidr. Consultado el 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr. Quota & Rate Limits. Documentación para desarrolladores de Kaleidr. Consultado el 17 de agosto de 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox. Cómo usar Mapbox de forma segura. Documentación de Mapbox. Consultado el 17 de agosto de 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox. Gestión de tokens. Documentación de Mapbox. Consultado el 17 de agosto de 2026. https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}