Obtenir une clé API

Kaleidr est une plateforme, un SDK et un système d’accès uniques — pour l’AI, les cartes et le design, gérés par des portées de capacité. Une clé existe sous deux formes sécurisées selon l’endroit où elle s’exécute ; les deux appartiennent à la même organisation et consomment le même quota.

Forme	Préfixe	Où elle s’exécute	Fonction
Publishable (navigateur)	kld_pk_live_…	dans HTML, le SDK, <kaleidr-map>	Verrouillée par origine et sûre dans le code source de la page. Le SDK l’échange contre une session de courte durée à l’exécution. Ne peut pas agir comme bearer serveur ni gérer les clés.
Server (backend)	kld_sk_live_…	uniquement sur vos serveurs	Bearer complet pour les appels serveur à serveur ; liste d’IP facultative, plafonds et expiration. Bloquée dans le navigateur (rejetée avec 403 server_key_in_browser).

Les anciennes clés kld_live_… existantes continuent de s’authentifier sans modification.

Ce que chaque forfait autorise

Voici la politique canonique forfait → portée × produit. Ce tableau est maintenu identique à B2B_TIER_API_CAPABILITIES dans @kaleidr/shared-types — la même constante que shared-api lit lors de la création d’une clé et que inference-api lit lors de l’échange de session — grâce à un contrôle de dérive CI, afin qu’aucune ligne ne puisse diverger silencieusement de ce que la plateforme autorise réellement.

Forfait	Publishable	Server	Portées autorisées	Produits autorisés
Free	Oui	— (403 free_plan_publishable_only)	maps	tile
Pro	Oui	Oui	ai, maps, design, vendor*	chat, editor, viewer, tile
Enterprise	Oui	Oui	ai, maps, design, vendor*	chat, editor, viewer, tile

* vendor nécessite une confirmation explicite pour chaque clé (sinon 403 vendor_scope_requires_acknowledgement).

Viewer ne nécessite jamais de clé — un share id constitue l’identifiant d’accès. Tous les forfaits (y compris Free) peuvent intégrer un Viewer sans aucune clé. Fournir une clé à un embed Viewer est rejeté avec product_not_allowed.

L’admission effective correspond à clé enregistrée × forfait actuel. Si une clé Pro est rétrogradée vers Free, le serveur l’échange contre une session conforme à Free — portée maps et produit tile uniquement. Réélargir une clé Free nécessite de créer une nouvelle clé avec le forfait supérieur plutôt que de modifier l’existante (voir Errors — Key management).

Clés de test

Les deux formes existent en variante test (kld_pk_test_…, kld_sk_test_…).

Une clé de test n’est pas un sandbox. Elle s’authentifie auprès de la même API, appelle les mêmes modèles et utilise la même allocation mensuelle qu’une clé live. Deux éléments diffèrent :

• une clé publishable de test peut être créée sans liste d’origines autorisées, contrairement à une clé live ;
• une clé de test ne peut pas servir de tuiles de fond de carte.

Utilisez des clés de test pour rendre le trafic de staging identifiable et révocable séparément — c’est leur véritable intérêt. Ne les considérez pas comme gratuites.

Créer une clé

1. Connectez-vous et ouvrez API Keys dans votre compte (kaleidr.com/api-keys) — réservé aux administrateurs de l’organisation.
2. Créez une clé — nommez-la et choisissez Browser (publishable) ou Server. Sur Pro et Enterprise, elle est créée avec toutes les autorisations du forfait (portées ai, maps, design ; produits chat, editor, viewer, tile) ; sur Free, il s’agit d’une clé Browser limitée à maps / tile, et l’option Server n’est pas proposée.
3. Une clé Browser live doit être verrouillée sur au moins une origine autorisée — une clé publishable live sans origine est rejetée car elle constituerait un secret permanent dans le code source de la page.
4. Copiez la valeur kld_pk_live_… / kld_sk_live_… une seule fois — elle n’est affichée qu’une fois et ne sera jamais réaffichée.

Deux prérequis pour chaque intégration

Aucun des deux n’est actuellement documenté sur une page produit, et chacun peut à lui seul bloquer une première intégration.

1. Liste des origines autorisées

L’échange de session vérifie l’en-tête Origin du navigateur par rapport à la liste des origines autorisées de la clé. Une non-correspondance est rejetée avec 403 session_origin_mismatch. file:// n’envoie aucun Origin — exactement comme un extrait copié est souvent testé la première fois — servez donc chaque embed avec clé via HTTP(S).

Mettez à jour la liste des origines autorisées d’une clé existante avec un JWT Cognito org-admin, et non avec la clé de plateforme elle-même :

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 invalide immédiatement le cache d’instantané de la clé, et supprimer une origine met également fin aux sessions déjà liées à celle-ci — chaque requête de session revérifie son origine par rapport aux allowed_origins actuelles de la clé. La requête suivante provenant d’une origine supprimée est donc rejetée au lieu de continuer jusqu’à expiration du TTL. L’ajout d’une origine fonctionne dans l’autre sens : il autorise de nouvelles sessions sans lier rétroactivement les sessions existantes.

2. CSP du client

La Content Security Policy de votre page doit autoriser les ressources chargées par chaque produit. Consultez Content Security Policy pour une configuration par produit — Tile et Viewer ajoutent uniquement le chargeur SDK et un hôte de frame ; Chat et Editor nécessitent également 'wasm-unsafe-eval' et les hôtes du fournisseur de cartes, puisque MapLibre s’exécute dans le document parent.

Utilisation

Dans le navigateur, fournissez la clé publishable et le SDK l’échangera contre une session de courte durée :

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

Depuis un serveur, envoyez la clé server comme bearer :

Authorization: Bearer kld_sk_live_…

La clé s’authentifie comme votre organisation. L’utilisation est décomptée du quota mensuel de l’organisation. Consultez Auth & scopes pour savoir ce que chaque portée débloque, et CORS & allowed origins pour la liste des origines de navigateur qui contrôle chaque échange de session.