Saltar al contenido principal

Obtener una clave de API

Una clave de API identifica a tu organización ante Kaleidr. Cada solicitud realizada desde el navegador o el servidor se comprueba conforme al plan de tu organización y se contabiliza en su consumo. Puedes crear y administrar claves en kaleidr.com/api-keys.

Necesitas una clave para usar Chat, Editor y Tile, y para llamar a la API del servidor. No necesitas una clave para insertar un mapa publicado con Viewer: basta con el ID del mapa.

Los dos tipos de claves​

Hay dos tipos de clave. Elige el adecuado según dónde se ejecute el código que la utiliza.

Clave publicableClave de servidor
Prefijokld_pk_live_…kld_sk_live_…
Dónde se usaEn una página web: el SDK y el elemento <kaleidr-map>Solo en tus servidores
¿Es segura en el código fuente de la página?SíNo. Trátala como una contraseña.
Cómo se utilizaEl SDK la intercambia por un token de sesión temporal, que realiza las llamadasSe envía directamente con cada solicitud mediante Authorization: Bearer o X-Api-Key
Restricciones disponiblesLos sitios incluidos en la lista de orígenes permitidosCualquier restricción configurada mediante la API de claves, como una lista de IP permitidas
PlanesFree, Pro, EnterprisePro, Enterprise
Nombre en la página API KeysBrowser / Embed KeyServer Key

Usa una clave publicable para todo lo que se ejecute en el navegador de un visitante. Está diseñada para ser visible. La protegen la lista de orígenes permitidos y la imposibilidad de llamar directamente a la API: si envías una clave publicable directamente a un endpoint, se rechaza con 401 publishable_requires_session.

Usa una clave de servidor cuando tu backend llame a Kaleidr: una tarea de geocodificación de direcciones, una ruta de API que transmita respuestas a tu interfaz o el backend de una aplicación móvil. Se rechaza una clave de servidor cuando la solicitud incluye una cabecera Origin (403 server_key_in_browser), como las que envían los navegadores. El SDK también la rechaza antes de realizar solicitudes. Nunca la incluyas en una página web ni en el binario de una aplicación móvil.

Ambos tipos pertenecen a la misma organización y consumen los mismos cupos. Consulta Cómo funciona Kaleidr para conocer las sesiones, organizaciones y la medición del consumo.

Las claves creadas antes de que existieran los dos tipos comienzan por kld_live_. Siguen funcionando y se envían directamente, como las claves de servidor.

Qué permite cada plan​

El plan de tu organización determina qué tipos de clave puedes crear, qué permisos puede tener una clave y qué productos puede montar.

PlanPublicableServidorPermisos admitidosProductos admitidos
FreeSí— (403 free_plan_publishable_only)ai, maps, designchat, editor, viewer, tile
ProSíSíai, maps, designchat, editor, viewer, tile
EnterpriseSíSíai, maps, design, vendor*chat, editor, viewer, tile

* vendor nunca se incluye de forma predeterminada y solo puede asignarse a claves Enterprise. Consulta Permisos.

Cada plan también limita cuántas claves activas puede tener una organización:

PlanClaves activas
Free2
Pro10
Enterprise25

Al superar el límite, la creación de una clave se rechaza con 409 key_limit_reached. Revoca una para crear otra. Rotar una clave no cuenta como una creación, pero la clave anterior sigue contando hasta que termine su período de gracia.

Cinco aspectos importantes de esta tabla:

  • Free admite todos los productos para navegador. Una organización Free puede usar Chat, Editor, Tile y Viewer en su sitio. Las respuestas de Chat consumen los créditos de IA mensuales; cuando se agotan, las solicitudes devuelven 429 hasta el siguiente período de facturación, la compra de un paquete adicional o una mejora del plan.
  • Viewer figura porque el plan lo permite, no porque necesite una clave. Los mapas publicados se insertan sin clave en cualquier plan.
  • Pro incorpora claves de servidor y más claves. Permite claves para el backend y hasta 10 claves activas en lugar de 2. Los productos y permisos admitidos son los mismos que en Free.
  • Utilizar datos empresariales propios en las respuestas de IA es exclusivo de Enterprise, en ambos sentidos. Un propietario o administrador Enterprise puede cargar datos empresariales conforme a los límites de su acuerdo; el asistente de Kaleidr Studio responde con esos datos para miembros autenticados. Free y Pro no pueden cargarlos. Solo Enterprise puede tener una clave con el permiso vendor que permita consultar esos datos por la API o el SDK. Solicitar vendor en Free o Pro provoca 403 tier_capability_not_allowed. Tus datos explica el proceso.
  • Todos los planes permiten añadir datasets a mapas de Kaleidr Studio. Los usuarios autenticados pueden subir hojas de cálculo y archivos geográficos desde Data. En Free, los límites son 50 000 filas por dataset, 32 MiB por archivo y 250 000 filas en toda la organización. En Pro son 100 000 filas, 64 MiB y 5 000 000 de filas. En Enterprise se mantienen los límites por dataset y archivo de Pro (100 000 filas y 64 MiB), y el total depende del contrato. Estos datos se muestran en el mapa y el asistente de Studio puede responder sobre ellos, pero no se consultan mediante una clave de API. Consulta Datasets en un mapa.

Los precios y cupos de cada plan están en la página de precios. Los cupos Enterprise son personalizados y se definen por contrato.

Permisos​

Un permiso (scope) es una autorización asociada a la clave. Cada producto o endpoint comprueba el permiso que necesita.

PermisoQué permiteEn una clave nueva
aiChat y los endpoints de chat, lugares y geocodificación de la API del servidorIncluido
mapsSesiones del mapa base TileIncluido
designEditor y los endpoints de diseño de la API del servidorIncluido
vendorPermite que las respuestas de Chat se basen en los datos empresariales publicados de tu organizaciónNo incluido: debe solicitarse. Solo Enterprise.

Las claves creadas desde la página API Keys siempre incluyen ai, maps y design; esa página no permite elegir permisos. Para crear una con vendor (solo Enterprise) o excluir algún permiso predeterminado, usa la API de claves.

Los permisos se fijan al crear la clave. Después no se pueden editar. Una rotación mantiene los permisos, salvo dos excepciones: los que el plan actual ya no admite se excluyen de la clave nueva y, en Free, la nueva clave incluye todos los permisos disponibles de ese plan (consulta Cuando cambia tu plan). Para cambiar los permisos, crea una clave nueva y revoca la antigua.

Cuando cambia tu plan​

Lo que puede hacer una clave es la intersección entre sus permisos y lo que permite el plan actual. Se comprueba en cada solicitud.

De Enterprise a Pro o Free. Las claves existentes siguen funcionando. Una clave con vendor conserva ese permiso en su configuración, pero deja de aplicarse: las respuestas ya no incluyen datos empresariales propios, sin mostrar un error. Las solicitudes se responden mediante conocimiento general. Las sesiones del navegador emitidas antes del cambio finalizan: la siguiente solicitud devuelve 401 y el SDK obtiene otra sesión con el plan nuevo. En Pro, rotar una clave así devuelve otra sin vendor; los demás permisos y la lista de productos no cambian. La organización ya no puede cargar datos empresariales: esas llamadas devuelven 403 vendor_data_not_on_plan. Los propietarios y administradores aún pueden enumerar, despublicar y eliminar los conjuntos de datos publicados que ya habían cargado.

Al pasar a Free. No se pueden crear claves de servidor ni rotar claves de servidor o heredadas: se rechaza con 403 free_plan_publishable_only. Rotar una clave publicable en Free devuelve otra con toda la oferta del plan (ai, maps, design y los cuatro productos), independientemente de sus permisos anteriores. Los datasets ya agregados a Kaleidr Studio permanecen; cada nueva carga se comprueba según los límites de datasets de Free. Las sesiones de navegador existentes terminan del mismo modo y el SDK obtiene otras.

Si vuelves a subir de plan se restauran las capacidades permitidas. Una clave que siga almacenando vendor vuelve a acceder a tus datos en Enterprise. Una clave rotada mientras estabas en un plan inferior no recupera ese permiso: crea otra.

Crear una clave​

Debes ser propietario o administrador de tu organización.

  1. Inicia sesión en kaleidr.com y abre kaleidr.com/api-keys. La página muestra las claves de tu organización en Your API Keys.
  2. Selecciona Create Key. Se abre el cuadro Create a Key con tres campos.
  3. Key Name. Pon una etiqueta, como Production site. Los visitantes nunca la ven. Usa nombres que indiquen dónde se ejecuta cada clave, para distinguirlas al revocarlas.
  4. Key Type. Elige Browser / Embed Key (publicable) o Server Key. Free no muestra la opción Server Key. El tipo no puede modificarse después.
  5. Allowed Origins. En una clave publicable, introduce los sitios autorizados separados por comas, como https://www.example.com, https://app.example.com. Déjalo vacío para permitir todos los sitios. Consulta Orígenes permitidos para conocer el formato. Una clave de servidor no está vinculada a un sitio, por lo que este campo debe quedar vacío.
  6. Selecciona Create Key.
  7. Copia la clave ahora. El cuadro muestra la clave completa una sola vez y advierte: «Copy this key now — it won't be shown again». Selecciona Copy, guárdala y después pulsa Done. Kaleidr no conserva el valor completo; si lo pierdes, rota la clave para obtener otra.

Resultado esperado: aparece una fila con el comienzo de la nueva clave en Key, su nombre, tipo (Browser o Server), estado Active y la fecha de hoy.

Si aparece "You must be an organization admin to manage API keys.", pide a un propietario o administrador que cree la clave o cambie tu función.

Orígenes permitidos​

Los orígenes permitidos son los sitios desde los que puede utilizarse una clave publicable. Al intercambiar la clave por una sesión, el navegador envía el origen de la página en la cabecera Origin y Kaleidr lo compara con la lista.

  • Una lista vacía permite cualquier sitio. Es útil en desarrollo, pero cualquiera que copie la clave del código fuente de tu página puede usarla en su sitio y gastar tu cupo. Define una lista para todas las claves de producción.
  • Una lista con al menos una entrada solo permite las entradas especificadas. La coincidencia es exacta: https://example.com no incluye https://www.example.com y http://localhost:3000 no incluye http://localhost:5173. Añade cada uno por separado.

Un origen consta de protocolo, host y puerto opcional, sin ruta:

Entrada¿Aceptada?
https://www.example.comSí
https://app.example.com:8443Sí
http://localhost:8000Sí. http se acepta solo en localhost y 127.0.0.1. http://[::1] puede configurarse mediante la API de administración de claves, pero no en esta página.
http://www.example.comNo. Los sitios que no sean locales deben usar https.
https://www.example.com/storeNo. Un origen no contiene rutas.
*.example.comNo. No admite comodines. https://*.example.com se guarda literalmente y no coincide con ningún sitio.

Cada clave admite un máximo de 100 orígenes.

Para modificar la lista, usa el icono de edición (lápiz) de la fila. En el cuadro Edit Key, cambia Allowed Origins y selecciona Save changes. Ahí también puedes cambiar el nombre de la clave.

  • Añadir un origen surte efecto para las nuevas sesiones de ese sitio.
  • Eliminarlo bloquea el sitio. Las sesiones previamente emitidas a páginas de ese origen fallan en su próxima solicitud con 401 Invalid or missing API key, sin esperar a que caduquen.

Qué ocurre en un sitio bloqueado. Cuando una página en un origen no autorizado intenta montar un producto, el intercambio se rechaza con 403 origin_not_allowed. La respuesta no incluye cabeceras CORS, por lo que el navegador informa de un error CORS al solicitar …/b2b/v1/sdk/sessions, el SDK registra un error [kaleidr:<product>] y no aparece nada. Solución de problemas muestra el texto exacto.

La lista de orígenes permitidos limita los sitios donde la clave funciona en un navegador. No convierte la clave publicable en un secreto: las solicitudes fuera del navegador pueden enviar el valor Origin que deseen. El Modelo de seguridad explica el alcance de esta protección y CORS y orígenes permitidos detalla las solicitudes.

Rotar y revocar​

Rota una clave para sustituirla sin interrumpir el servicio. Selecciona la acción de rotación en su fila y confirma. Kaleidr emite una clave nueva con el mismo tipo, permisos y orígenes permitidos, y muestra su valor una sola vez. La clave anterior sigue funcionando durante 24 horas, para que puedas desplegar la nueva antes de que caduque. Durante ese plazo, cuenta para el límite del plan y no puede volver a rotarse.

Rota una clave cuando se marcha una persona que tenía acceso a ella, o según las normas de tu política de seguridad. Si la clave se ha filtrado, revócala: rotarla desde esta página mantendría el valor antiguo activo durante 24 horas.

Revoca una clave para detenerla inmediatamente. Selecciona la acción de eliminar (papelera) de su fila y confirma. La página advierte: «Revoke this API key? Any site using it will stop working immediately». La revocación también finaliza todas las sesiones emitidas con esa clave, de modo que las páginas abiertas fallan en su siguiente solicitud. Una clave revocada no puede recuperarse.

Cuando se filtre una clave de servidor, revócala en lugar de rotarla: el período de gracia de 24 horas dejaría activa la clave comprometida.

Claves de prueba​

Ambos tipos de clave tienen una variante de prueba: kld_pk_test_… y kld_sk_test_….

Una clave de prueba no es un entorno aislado. Usa la misma API, produce las mismas respuestas y consume los mismos créditos de IA y cargas de mapas que una clave real. La única diferencia es que no puede cargar los mosaicos del mapa base.

Su ventaja es separar los entornos: el tráfico del sitio de pruebas se asocia a una clave propia que puedes revocar sin afectar a producción. No consideres gratuito ese tráfico.

La página API Keys solo crea claves activas. Para crear una de prueba, usa la API de claves con "environment": "test".

Opciones que la página no ofrece​

La página API Keys permite configurar nombre, tipo y orígenes permitidos. La API de claves, disponible en https://api.kaleidr.com/shared-api/api-keys, ofrece opciones adicionales.

La API de claves autentica a tu usuario, no a una clave: envía el token de acceso de un propietario o administrador autenticado como Authorization: Bearer. Una clave de API no puede crear ni modificar claves.

CampoTipoPredeterminadoFunción
namecadena, 1–200 caracteresobligatorioEtiqueta de la clave.
org_idUUIDtu organización principalOrganización de la clave. Envíalo en el cuerpo: al crearla se ignora un org_id de la consulta.
key_type"publishable" o "server""publishable"Tipo de clave, fijo tras crearla.
environment"live" o "test""live"Crea una clave activa o de prueba. No puede cambiarse después.
scopesmatriz de cadenas["ai", "maps", "design"]Permisos de la clave. Fijos tras crearla.
vendor_acknowledgedbooleanofalseDebe ser true para crear una clave publicable con vendor.
allowed_originsmatriz de cadenas, hasta 100[]Orígenes permitidos. Solo claves publicables.
allowed_productsmatriz de cadenas[] (todos los productos)Restringe la clave a algunos de chat, editor, viewer, tile. Se aplica a todos los tipos de clave: consulta la nota siguiente.
allowed_ipsmatriz de cadenas, hasta 100[] (cualquier dirección)Direcciones IP o rangos CIDR desde los que puede usarse una clave de servidor.
monthly_cap_tokensentero, 0 o másningunoMáximo de créditos de IA que puede gastar la clave por período. Un valor de 1 o más establece un límite; 0 o null significa sin límite.
expires_atfecha y hora futurasningunaCuándo deja de funcionar la clave.

En Free, scopes y allowed_products siempre se establecen con todo lo que el plan permite (ai, maps, design; chat, editor, viewer, tile), aunque la solicitud indique otra cosa. Lo mismo ocurre al rotar una clave en Free. En todos los planes, solicitar un permiso o producto que el plan no admite se rechaza con 403 tier_capability_not_allowed; nunca se omite silenciosamente.

Las restricciones de producto se aplican en todos los usos de la clave. Una clave publicable limitada a ciertos productos recibe 403 product_not_allowed al intercambiar la sesión si intenta montar otro producto. Las claves de servidor o heredadas reciben el mismo 403 product_not_allowed en cada solicitud a endpoints de productos no permitidos: chat, lugares y geocodificación pertenecen a chat, y los endpoints de diseño a editor. Para que una clave de servidor acceda a todos los endpoints autorizados por sus permisos, deja allowed_products vacío. Consulta la tabla de correspondencias en Autenticación y permisos.

Esta solicitud crea una clave publicable de prueba limitada a Chat en un sitio de ensayo:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging site chat",
    "key_type": "publishable",
    "environment": "test",
    "allowed_origins": ["https://staging.example.com"],
    "allowed_products": ["chat"]
  }'

La respuesta 201 contiene la configuración de la clave y, una sola vez, su valor completo en plaintext_key:

{
  "id": "5f0c2a9e-…",
  "name": "Staging site chat",
  "key_prefix": "kld_pk_test_…",
  "key_type": "publishable",
  "environment": "test",
  "scopes": ["ai", "maps", "design"],
  "allowed_origins": ["https://staging.example.com"],
  "allowed_products": ["chat"],
  "allowed_ips": [],
  "monthly_cap_tokens": null,
  "status": "active",
  "expires_at": null,
  "plaintext_key": "kld_pk_test_…"
}

Una clave que puede leer tus datos empresariales​

El permiso vendor permite que las respuestas de Chat utilicen datos empresariales publicados por tu organización. Tanto cargar esos datos como obtener el permiso para consultarlos mediante una clave están disponibles solo en Enterprise; el permiso se concede únicamente mediante la API de claves:

curl -X POST https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site chat with our data",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

vendor_acknowledged es necesario porque la clave publicable aparece en el código de la página: cualquiera que pueda abrirla puede hacer preguntas a Chat, cuyas respuestas pueden incluir datos cargados por ti. Al establecerlo en true confirmas expresamente que aceptas ese acceso.

  • Una clave publicable que solicita vendor sin "vendor_acknowledged": true se rechaza con 422 vendor_scope_requires_acknowledgement.
  • Las claves de servidor no requieren confirmación.
  • En Free y Pro, cualquier solicitud con vendor se rechaza con 403 tier_capability_not_allowed, se envíe o no vendor_acknowledged. No se crea ninguna clave.

Tus datos explica cómo cargarlos y comprobar que se hayan utilizado en una respuesta.

Modificar una clave (PATCH /shared-api/api-keys/{id}) admite name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens y expires_at. Rotarla (POST /shared-api/api-keys/{id}/rotate) acepta grace_hours de 0 a 8760; por defecto 0, la clave anterior se desactiva inmediatamente. Revocarla utiliza POST /shared-api/api-keys/{id}/revoke. Los códigos de rechazo aparecen en Errores.

Dos requisitos previos para cada integración​

Una clave válida no basta para mostrar un producto autenticado. La propia página también debe cumplir dos requisitos y, si falla, el navegador informa de errores que no siempre revelan la causa.

1. La página se sirve desde un origen permitido por la clave​

  • Sirve la página mediante HTTP o HTTPS, también durante el desarrollo. Un archivo abierto desde el disco (file://) carece de un origen que pueda añadirse a la clave.
  • Si la clave tiene una lista de orígenes permitidos, el de tu página debe aparecer exactamente en ella, con protocolo, host y puerto. Para pruebas locales suele ser http://localhost:<port>.

Si esto falla, no aparece nada y la consola informa de un error CORS durante el intercambio de sesión. Parece un fallo de red, pero se debe a los orígenes permitidos.

2. La política de seguridad de contenido permite cargar el producto​

Si tu sitio envía una cabecera Content-Security-Policy, debe permitir los servidores Kaleidr que utiliza cada producto. Si no envía esa cabecera, no necesita configurar nada.

ProductoQué debe permitir tu política
Viewer, TileScripts de https://cdn.kaleidr.com, un iframe de https://map-embed.kaleidr.com y, si necesita una clave, conexión a https://api.kaleidr.com
Chat, EditorScripts de https://cdn.kaleidr.com, conexiones a https://api.kaleidr.com y estilos insertados, porque ambos productos añaden CSS a la página. Editor también carga el mapa base desde https://tile.kaleidr.com.

Política de seguridad de contenido recoge todas las directivas de cada producto.

Si la política bloquea un recurso, el navegador muestra un mensaje Refused to load… o Refused to connect…, con la dirección y la directiva responsables.

Usar la clave​

En una página web, envía una clave publicable al producto. El SDK la cambia por una sesión y la mantiene renovada mientras el producto esté montado.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map
  product="tile"
  publishable-key="kld_pk_live_…"
  style-id="kaleidr-morning"
  style="display:block; height:480px"
></kaleidr-map>

Resultado esperado: el mapa base aparece y la pestaña Network muestra una respuesta 200 de https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions. La Guía de inicio rápido contiene una página completa por producto.

Desde un servidor, envía la clave de servidor en cada solicitud. Esta llamada enumera los estilos de mapa que conocen los endpoints de diseño y no consume créditos de IA, por lo que sirve para comprobar por primera vez la clave.

curl https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer kld_sk_live_…"

Resultado esperado: una respuesta 200 con un objeto JSON que contiene una matriz styles. Un 401 con {"detail":"Invalid or missing API key"} indica que la clave es incorrecta o está revocada. Un 403 con {"detail":"server_key_in_browser"} indica que la solicitud llevaba una cabecera Origin; elimínala. Consulta Inicio rápido del servidor para continuar.

Próximos pasos​