Obtener una clave API
Kaleidr es una plataforma, un SDK y un sistema de acceso — para AI, mapas y diseño, gestionados mediante ámbitos de capacidad. Una clave se ofrece en dos formas seguras según dónde se ejecute; ambas pertenecen a la misma organización y consumen la misma cuota.
| Forma | Prefijo | Dónde se ejecuta | Qué hace |
|---|---|---|---|
| Publishable (navegador) | kld_pk_live_… | en HTML, el SDK, <kaleidr-map> | Restringida por origen y segura para aparecer en el código fuente de la página. El SDK la intercambia por una sesión de corta duración en tiempo de ejecución. No puede actuar como bearer de servidor ni administrar claves. |
| Server (backend) | kld_sk_live_… | solo en tus servidores | Bearer completo para llamadas servidor a servidor; lista de IP opcional, límites y vencimiento. Bloqueada en el navegador (rechazada con 403 server_key_in_browser). |
Las claves heredadas kld_live_… existentes siguen autenticándose sin cambios.
Qué permite cada plan
Esta es la política canónica plan → ámbito × producto. Esta tabla se mantiene igual a
B2B_TIER_API_CAPABILITIES en @kaleidr/shared-types — la misma constante que
shared-api consulta al crear claves y inference-api durante el intercambio
de sesión — mediante un control de deriva en CI, de modo que ninguna fila pueda discrepar silenciosamente
de lo que realmente permite la plataforma.
| Plan | Publishable | Server | Ámbitos permitidos | Productos permitidos |
|---|---|---|---|---|
| Free | Sí | — (403 free_plan_publishable_only) | maps | tile |
| Pro | Sí | Sí | ai, maps, design, vendor* | chat, editor, viewer, tile |
| Enterprise | Sí | Sí | ai, maps, design, vendor* | chat, editor, viewer, tile |
* vendor requiere una confirmación explícita por clave (de lo contrario, 403
vendor_scope_requires_acknowledgement).
Viewer nunca necesita una clave — un ID de uso compartido es la credencial. Cualquier plan (incluido Free)
puede integrar un Viewer sin clave. Pasar una clave a una integración Viewer
se rechaza con product_not_allowed.
La admisión efectiva es clave almacenada × nivel actual. Si una clave Pro
se reduce a Free, el servidor la intercambia por una sesión con forma de Free —
solo ámbito maps y producto tile. Ampliar de nuevo una clave Free requiere
crear una nueva clave en el plan superior, no editar la existente (consulta
Errors — Key management).
Claves de prueba
Ambas formas están disponibles en una variante test (kld_pk_test_…, kld_sk_test_…).
Una clave de prueba no es un sandbox. Se autentica contra la misma API, utiliza los mismos modelos y consume la misma asignación mensual que una clave en vivo. Hay dos diferencias:
- una clave publishable de prueba puede crearse sin una lista de orígenes permitidos, mientras que una clave en vivo no;
- una clave de prueba no puede servir teselas de mapas base.
Utiliza claves de prueba para mantener el tráfico de staging identificable y revocable de manera independiente — ese es su verdadero valor. No las trates como gratuitas.
Crear una clave
- Inicia sesión y abre API Keys dentro de tu cuenta (kaleidr.com/api-keys) — solo para administradores de la organización.
- Crea una clave — asígnale un nombre y elige Browser (publishable) o
Server. En Pro y Enterprise se crea con toda la admisión del nivel
(ámbitos
ai,maps,design; productoschat,editor,viewer,tile); en Free es una clave Browser restringida amaps/tile, y la opción Server no está disponible. - Una clave Browser en vivo debe estar limitada a al menos un origen permitido — una clave publishable en vivo sin orígenes se rechaza porque sería un secreto permanente visible en el código fuente de la página.
- Copia el valor
kld_pk_live_…/kld_sk_live_…una sola vez — se muestra una única vez y nunca vuelve a mostrarse.
Dos requisitos para cada integración
Actualmente ninguno de los dos está documentado en las páginas de producto, y cualquiera de ellos puede bloquear por sí solo una primera integración.
1. Lista de orígenes permitidos
El intercambio de sesión compara el encabezado Origin del navegador con la lista de orígenes permitidos
de la clave. Una discrepancia se rechaza con 403 session_origin_mismatch. file://
no envía ningún Origin — que es exactamente cómo suele probarse por primera vez
un fragmento copiado — así que sirve todas las integraciones con clave mediante HTTP(S).
Actualiza la lista de orígenes permitidos de una clave existente con un JWT de Cognito org-admin, no con la propia clave de plataforma:
PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json
{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }
PATCH invalida inmediatamente la caché de instantánea de la clave, y eliminar un
origen también finaliza las sesiones que ya estaban vinculadas a él — cada solicitud de sesión
vuelve a comprobar su origen frente a los allowed_origins actuales de la clave, por lo que la siguiente
solicitud desde un origen eliminado se rechaza en lugar de esperar a que finalice su TTL.
Añadir un origen funciona en sentido contrario: permite nuevas sesiones y no vincula
retroactivamente las existentes.
2. CSP del cliente
La Content Security Policy de tu página debe permitir los recursos que carga cada producto.
Consulta Content Security Policy
para una configuración por producto — Tile y Viewer solo añaden el cargador del SDK y un
host de frame; Chat y Editor además necesitan 'wasm-unsafe-eval' y los hosts del
proveedor de mapas porque MapLibre se ejecuta en el documento principal.
Cómo usarla
En el navegador, pasa la clave publishable y el SDK la intercambiará por una sesión de corta duración:
<kaleidr-map product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="height:480px"></kaleidr-map>
Desde un servidor, envía la clave server como bearer:
Authorization: Bearer kld_sk_live_…
La clave se autentica como tu organización. El uso se descuenta de la cuota mensual de la organización. Consulta Auth & scopes para saber qué habilita cada ámbito y CORS & allowed origins para conocer la lista de orígenes del navegador que controla cada intercambio de sesión.