Obtenir une clé API

Une clé API identifie votre organisation auprès de Kaleidr. Chaque requête effectuée depuis un navigateur ou un serveur est autorisée selon le forfait de votre organisation et comptabilisée dans son utilisation. Créez et gérez vos clés sur kaleidr.com/api-keys.

Une clé est nécessaire pour Chat, Editor, Tile et l'API serveur. Vous n'avez pas besoin de clé pour intégrer une carte publiée avec Viewer : son identifiant suffit.

Les deux types de clés

Il existe deux types de clés. Le choix dépend de l'endroit où s'exécute le code qui l'utilise.

	Clé publiable	Clé serveur
Préfixe	kld_pk_live_…	kld_sk_live_…
Où l'utiliser	Dans une page web : SDK et élément <kaleidr-map>	Uniquement sur vos serveurs
Peut figurer dans le code source de la page	Oui	Non. Traitez-la comme un mot de passe.
Fonctionnement	Le SDK l'échange contre un jeton de session temporaire, utilisé ensuite pour les appels	Transmise directement à chaque requête avec Authorization: Bearer ou X-Api-Key
Restrictions possibles	Sites de la liste des origines autorisées	Restrictions de l'API de gestion des clés, notamment les adresses IP autorisées
Forfaits	Free, Pro, Enterprise	Pro, Enterprise
Nom sur la page API Keys	Browser / Embed Key	Server Key

Utilisez une clé publiable pour le code exécuté dans le navigateur des visiteurs. Sa visibilité est prévue. Sa protection repose sur la liste des origines autorisées et sur l'impossibilité d'appeler directement l'API : une clé publiable envoyée directement à un endpoint est refusée avec 401 publishable_requires_session.

Utilisez une clé serveur si votre backend appelle Kaleidr, par exemple pour géocoder des adresses, diffuser une réponse vers votre interface via une route API ou servir une application mobile. Toute requête avec l'en-tête Origin, envoyé par les navigateurs, est refusée pour une clé serveur (403 server_key_in_browser). Le SDK refuse également de démarrer avec une telle clé, avant tout appel. Ne placez jamais une clé serveur dans une page web ou un binaire mobile.

Les deux types appartiennent à la même organisation et puisent dans les mêmes quotas. Consultez Fonctionnement de Kaleidr pour les sessions, les organisations et le comptage.

Les clés créées avant l'existence de ces deux types commencent par kld_live_. Elles continuent à fonctionner et sont transmises directement, comme des clés serveur.

Ce que permet chaque offre

Le forfait de votre organisation détermine quels types de clés elle peut créer, quelles autorisations chaque clé peut porter et quels produits elle peut monter.

Forfait	Publiable	Serveur	Autorisations admises	Produits admis
Free	Oui	— (403 free_plan_publishable_only)	ai, maps, design	chat, editor, viewer, tile
Pro	Oui	Oui	ai, maps, design	chat, editor, viewer, tile
Enterprise	Oui	Oui	ai, maps, design, vendor*	chat, editor, viewer, tile

* vendor n'est jamais inclus par défaut et n'est disponible que pour les clés Enterprise. Voir Autorisations.

Chaque forfait limite également le nombre de clés actives par organisation :

Forfait	Clés actives
Free	2
Pro	10
Enterprise	25

Au-delà de cette limite, la création est refusée avec 409 key_limit_reached : révoquez une clé pour en créer une autre. La rotation n'est pas comptabilisée comme une création, mais l'ancienne clé reste comptée jusqu'à la fin de son délai de grâce.

Cinq précisions concernant ce tableau :

• Free permet tous les produits destinés au navigateur. Une organisation Free peut utiliser Chat, Editor, Tile et Viewer. Les réponses de Chat consomment les crédits IA mensuels Free. Une fois épuisés, les appels renvoient 429 jusqu'à la prochaine période de facturation, l'achat d'un pack complémentaire ou un changement de forfait.
• Viewer figure dans la liste parce que le forfait l'autorise, pas parce qu'une clé est nécessaire. Une carte publiée s'intègre sans clé avec tous les forfaits.
• Pro apporte les clés serveur et un nombre supérieur de clés. Une organisation Pro peut créer des clés serveur pour son backend et disposer de 10 clés actives au lieu de 2. Les produits et autorisations accessibles sont ceux de Free.
• L'utilisation de vos données métier dans les réponses IA est réservée à Enterprise, des deux côtés. Un propriétaire ou administrateur Enterprise peut importer des données métier selon les limites contractuelles ; l'assistant Kaleidr Studio les utilise pour les membres connectés de l'organisation. Free et Pro ne peuvent pas en importer. Seules les organisations Enterprise peuvent créer des clés avec l'autorisation vendor pour lire ces données via l'API ou le SDK. Demander une clé contenant vendor sous Free ou Pro renvoie 403 tier_capability_not_allowed. Voir Vos données.
• Tous les forfaits permettent l'ajout de jeux de données aux cartes Studio. Un utilisateur connecté importe des feuilles de calcul et des fichiers géographiques depuis Data. Free autorise 50 000 lignes par jeu de données, 32 MiB par fichier et 250 000 lignes dans l'organisation. Pro autorise 100 000 lignes, 64 MiB et 5 000 000 de lignes. Enterprise applique les mêmes plafonds par jeu et fichier que Pro (100 000 lignes, 64 MiB), avec un plafond total défini contractuellement. Ces données sont dessinées sur la carte, visibles dans Studio et sur la carte publiée, et l'assistant IA de Studio peut y répondre ; elles ne sont pas accessibles via une clé API. Voir Jeux de données cartographiques.

Tarifs et quotas sont indiqués sur la page des prix. Les plafonds Enterprise sont personnalisés et définis dans le contrat.

Portées

Un scope est une autorisation attachée à une clé. Chaque produit ou endpoint vérifie celui dont il a besoin.

Scope	Fonction permise	Sur une nouvelle clé
ai	Chat et les endpoints de chat, lieux et géocodage de l'API serveur	Inclus
maps	Sessions de fond de carte Tile	Inclus
design	Editor et les endpoints de conception de l'API serveur	Inclus
vendor	Permet de répondre avec les données métier publiées de votre organisation	Non inclus ; à demander. Enterprise seulement.

Une clé créée sur la page API Keys possède toujours ai, maps et design ; cette page ne propose aucun sélecteur. Pour demander vendor (Enterprise seulement), ou exclure un scope par défaut, utilisez l'API des clés.

Les scopes sont fixés à la création. Impossible de les modifier ensuite. La rotation conserve les scopes, sauf si le forfait actuel n'en autorise plus certains, qui sont retirés du remplacement, ou si vous êtes sur Free, qui attribue toujours toutes ses autorisations (voir Changement de forfait). Pour changer les scopes, créez une nouvelle clé puis révoquez l'ancienne.

Lorsque votre offre change

Les actions possibles correspondent à l'intersection entre les autorisations de la clé et celles de votre forfait actuel ; cette vérification a lieu à chaque requête.

D'Enterprise vers Pro ou Free. Les clés existantes continuent à fonctionner. Le scope vendor reste enregistré mais cesse de s'appliquer : les réponses n'utilisent plus les données métier, sans afficher d'erreur. Les requêtes aboutissent avec des réponses fondées sur les connaissances générales. Les sessions navigateur émises avant le changement sont invalidées : leur prochaine requête renvoie 401, puis le SDK obtient une session du nouveau forfait. Sous Pro, la rotation d'une telle clé crée une remplaçante sans vendor, avec les autres scopes et produits inchangés. L'import de données métier est désormais refusé avec 403 vendor_data_not_on_plan. Les propriétaires et administrateurs peuvent toujours lister, dépublier et supprimer les versions importées.

Passage à Free. Impossible de créer de nouvelles clés serveur ou de faire tourner les clés serveur et anciennes : 403 free_plan_publishable_only. La rotation d'une clé publiable sur Free crée une remplaçante autorisant toute l'offre Free (ai, maps, design et les quatre produits), quels que soient les anciens paramètres. Les jeux de données déjà ajoutés aux cartes Studio restent en place ; toute nouvelle importation est soumise aux limites Free. Les sessions navigateur antérieures sont invalidées, puis renouvelées par le SDK.

Un retour à un forfait supérieur rétablit les fonctionnalités admises. Une clé conservant le scope vendor retrouve l'accès aux données sous Enterprise. Une clé remplacée par rotation sous un forfait inférieur ne récupère pas ce scope : créez-en une nouvelle.

Créer une clé

Vous devez être propriétaire ou administrateur de votre organisation.

1. Connectez-vous sur kaleidr.com, puis ouvrez kaleidr.com/api-keys. Les clés de votre organisation apparaissent dans Your API Keys.
2. Cliquez sur Create Key. La boîte Create a Key s'ouvre avec trois champs.
3. Key Name. Donnez un nom descriptif, par exemple Production site. Les visiteurs ne le voient jamais. Utilisez un nom indiquant où fonctionne la clé afin de la reconnaître si vous devez la révoquer.
4. Key Type. Choisissez Browser / Embed Key (publiable) ou Server Key. Sous Free, l'option Server Key n'est pas affichée. Le type ne pourra plus être modifié.
5. Allowed Origins. Pour une clé publiable, saisissez les sites autorisés, séparés par des virgules, par exemple https://www.example.com, https://app.example.com. Un champ vide autorise tous les sites. Consultez Origines autorisées pour le format. Une clé serveur n'est pas liée à un site : laissez ce champ vide.
6. Cliquez sur Create Key.
7. Copiez la clé immédiatement. La boîte affiche sa valeur complète une seule fois avec l'avertissement « Copy this key now — it won't be shown again. » Cliquez sur Copy, conservez-la en lieu sûr puis sur Done. Kaleidr ne conserve pas sa valeur intégrale. En cas de perte, effectuez une rotation.

Résultat attendu : la nouvelle clé apparaît dans le tableau, avec ses premiers caractères sous Key, son nom, son type (Browser ou Server), le statut Active et la date du jour.

Si le message "You must be an organization admin to manage API keys." apparaît, demandez à un propriétaire ou administrateur de créer la clé ou de modifier votre rôle.

Origines autorisées

Les origines autorisées sont les sites depuis lesquels une clé publiable fonctionne. Lors de l'échange contre une session, le navigateur transmet l'origine de la page dans l'en-tête Origin, que Kaleidr compare à la liste.

• Une liste vide autorise tous les sites. Pratique pour développer, mais quiconque copie votre clé depuis le code source de la page peut l'utiliser sur son site et consommer votre quota. Définissez une liste pour toutes les clés de production.
• Une liste non vide n'autorise que ses entrées. La correspondance est exacte : https://example.com n'inclut pas https://www.example.com, ni http://localhost:3000 ne couvre http://localhost:5173. Ajoutez chaque origine séparément.

Une origine comporte un protocole, un hôte et éventuellement un port, sans chemin :

Entrée	Acceptée
https://www.example.com	Oui
https://app.example.com:8443	Oui
http://localhost:8000	Oui. http n'est accepté que pour localhost et 127.0.0.1. http://[::1] peut être configuré via l'API de gestion des clés, mais pas sur cette page.
http://www.example.com	Non. Les sites non locaux doivent utiliser https.
https://www.example.com/store	Non. Une origine ne contient aucun chemin.
*.example.com	Non. Aucun caractère générique. https://*.example.com est enregistré tel quel sans correspondre à aucun site.

Une clé accepte au maximum 100 origines.

Pour modifier la liste, utilisez l'icône d'édition (crayon) de la ligne. Dans Edit Key, modifiez Allowed Origins puis cliquez sur Save changes. Ce dialogue permet aussi de renommer la clé.

• Ajouter une origine autorise les nouvelles sessions provenant de ce site.
• Supprimer une origine bloque ce site. Les sessions qui y ont déjà été émises échouent à leur prochaine requête avec 401 Invalid or missing API key, sans attendre leur expiration.

Ce que voit un site bloqué. Si une page d'origine non autorisée essaie de monter un produit, l'échange est refusé avec 403 origin_not_allowed. La réponse ne comporte aucun en-tête CORS, le navigateur signale donc une erreur CORS pour …/b2b/v1/sdk/sessions, le SDK journalise une erreur [kaleidr:<product>] et rien ne s'affiche. Consultez Dépannage pour le texte exact.

Cette liste limite les sites depuis lesquels la clé fonctionne dans un navigateur ; elle ne rend pas une clé publiable secrète. Un client non navigateur peut envoyer n'importe quelle valeur Origin. Le Modèle de sécurité explique les protections et leurs limites, et CORS et origines autorisées décrit les requêtes.

Renouveler et révoquer une clé

Effectuez une rotation pour remplacer une clé sans interruption de service. Choisissez l'action de rotation et confirmez. Kaleidr crée une clé du même type, avec les mêmes scopes et origines autorisées, et affiche sa valeur une seule fois. L'ancienne fonctionne encore 24 heures pour laisser le temps de déployer la nouvelle. Pendant ce délai, elle compte dans le plafond de clés et ne peut pas être soumise à une nouvelle rotation.

Effectuez une rotation quand une personne ayant accès à la clé quitte l'équipe, ou selon votre politique de sécurité. Si la clé a fuité, révoquez-la plutôt : une rotation effectuée sur cette page laisse l'ancienne valeur utilisable durant 24 heures.

Révoquez une clé pour l'arrêter immédiatement. Choisissez l'action de suppression (corbeille) sur sa ligne et confirmez. La page avertit : « Revoke this API key? Any site using it will stop working immediately. » La révocation met également fin à toutes les sessions issues de cette clé : les pages déjà ouvertes échouent à leur prochaine requête. Une clé révoquée ne peut pas être restaurée.

Révoquez, sans faire de rotation, toute clé serveur compromise : les 24 heures de grâce laisseraient la valeur divulguée fonctionner.

Clés de test

Chaque type de clé existe en version de test : kld_pk_test_… et kld_sk_test_….

Une clé de test n'est pas un bac à sable. Elle appelle la même API, reçoit les mêmes réponses et consomme les mêmes crédits IA et chargements de cartes qu'une clé de production. Seule différence : elle ne peut pas charger les tuiles des fonds de carte.

La clé de test sert à isoler le trafic de préproduction dans une clé indépendante, révocable sans toucher à la production. Ne supposez pas que le trafic de test est gratuit.

La page API Keys ne crée que des clés actives. Pour une clé de test, utilisez l'API des clés avec "environment": "test".

Options non disponibles sur la page

La page API Keys permet de définir nom, type et origines autorisées. D'autres réglages sont accessibles via l'API à https://api.kaleidr.com/shared-api/api-keys.

Cette API vous authentifie en tant qu'utilisateur, pas avec une clé : transmettez le jeton d'accès d'un propriétaire ou administrateur connecté comme Authorization: Bearer. Une clé API ne peut pas créer ou modifier d'autres clés.

Champ	Type	Valeur par défaut	Fonction
name	chaîne de 1 à 200 caractères	obligatoire	Libellé de la clé.
org_id	UUID	organisation principale	Organisation destinataire. Envoyez-le dans le corps : le paramètre de requête org_id est ignoré lors de la création.
key_type	"publishable" ou "server"	"publishable"	Type fixé lors de la création.
environment	"live" ou "test"	"live"	Crée une clé réelle ou de test, non modifiable ensuite.
scopes	tableau de chaînes	["ai", "maps", "design"]	Scopes de la clé, fixés à sa création.
vendor_acknowledged	booléen	false	Doit valoir true pour créer une clé publiable avec vendor.
allowed_origins	tableau de chaînes, jusqu'à 100	[]	Origines autorisées. Clés publiables seulement.
allowed_products	tableau de chaînes	[] (tous)	Limite à certains de chat, editor, viewer, tile. Applicable aux deux types de clés ; voir la note suivante.
allowed_ips	tableau de chaînes, jusqu'à 100	[] (toutes les adresses)	Adresses IP ou plages CIDR admises pour une clé serveur.
monthly_cap_tokens	entier positif ou nul	aucun	Maximum de crédits IA par période de facturation. À partir de 1, un plafond s'applique ; 0 ou null signifie sans plafond.
expires_at	date-heure future	aucune	Date de cessation de fonctionnement.

Sur Free, scopes et allowed_products prennent toujours toutes les valeurs autorisées (ai, maps, design ; chat, editor, viewer, tile), quelles que soient celles demandées, y compris lors d'une rotation. Pour tout forfait, demander un scope ou produit non admis renvoie 403 tier_capability_not_allowed : aucun élément de la requête n'est écarté silencieusement.

Les limitations par produit s'appliquent partout où la clé est utilisée. Une clé publiable limitée à certains produits reçoit 403 product_not_allowed au moment de l'échange de session si la page tente d'en monter un autre. Une clé serveur ou ancienne clé limitée reçoit le même 403 product_not_allowed pour chaque appel à un endpoint d'un autre produit : chat, lieux et géocodage appartiennent à chat, conception à editor. Pour qu'une clé serveur appelle tous les endpoints permis par ses scopes, laissez allowed_products vide. Voir le tableau des correspondances sous Authentification et scopes.

Cette requête crée une clé publiable de test limitée à Chat sur un site de préproduction :

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 réponse 201 contient ses paramètres et, une seule fois, la valeur intégrale dans 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_…"
}

Une clé pouvant accéder à vos données métier

Le scope vendor permet à Chat de s'appuyer sur les données métier publiées par votre organisation. Importer ces données et créer une clé qui peut les consulter sont deux fonctions réservées à Enterprise ; ce scope est accordé uniquement via l'API des clés :

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 est requis parce qu'une clé publiable figure dans votre code source : tous les visiteurs peuvent interroger Chat et les réponses peuvent contenir vos données importées. En donnant la valeur true, vous confirmez que cela est intentionnel.

• Une clé publiable demandant vendor sans "vendor_acknowledged": true est refusée avec 422 vendor_scope_requires_acknowledgement.
• Une clé serveur ne nécessite pas cette confirmation.
• Sous Free et Pro, toute demande contenant vendor est refusée avec 403 tier_capability_not_allowed, que vendor_acknowledged soit transmis ou non. Aucune clé n'est créée.

Vos données explique l'import et la vérification de l'utilisation des données dans les réponses.

Modifier une clé (PATCH /shared-api/api-keys/{id}) accepte name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens et expires_at. La rotation (POST /shared-api/api-keys/{id}/rotate) accepte grace_hours de 0 à 8760 ; par défaut 0, l'ancienne clé cesse immédiatement de fonctionner. La révocation utilise POST /shared-api/api-keys/{id}/revoke. Les codes d'erreur sont décrits sous Erreurs.

Deux conditions préalables à chaque intégration

Une clé valide ne suffit pas à afficher un produit qui en exige une. La page elle-même doit remplir deux conditions, et les erreurs du navigateur ne pointent pas forcément leur cause.

1. La page est servie depuis une origine autorisée

• Servez la page en HTTP ou HTTPS, même en développement. Un fichier ouvert directement (file://) n'a pas d'origine que l'on puisse autoriser.
• Si la clé définit des origines autorisées, celle de la page doit y figurer à l'identique : protocole, hôte et port. En local, il s'agit généralement de http://localhost:<port>.

Si ces conditions ne sont pas remplies, rien ne s'affiche et la console signale une erreur CORS lors de l'échange de session. Cela ressemble à un problème réseau, mais c'est la liste d'origines.

2. La politique de sécurité du contenu autorise le chargement du produit

Si votre site transmet l'en-tête Content-Security-Policy, il doit autoriser les domaines Kaleidr nécessaires à chaque produit. Sans cet en-tête, aucune configuration n'est requise.

Produit	Ce que la politique doit autoriser
Viewer, Tile	Scripts provenant de https://cdn.kaleidr.com, iframe de https://map-embed.kaleidr.com et, pour une intégration avec clé, connexion à https://api.kaleidr.com
Chat, Editor	Scripts provenant de https://cdn.kaleidr.com, connexions à https://api.kaleidr.com et styles intégrés, car les deux produits ajoutent des styles à la page. Editor charge aussi le fond de carte depuis https://tile.kaleidr.com.

La page Content Security Policy fournit toutes les directives nécessaires produit par produit.

En cas de blocage, le navigateur affiche Refused to load… ou Refused to connect… en précisant l'adresse bloquée et la directive.

Utiliser la clé

Dans une page web, passez au produit une clé publiable. Le SDK l'échange contre une session et renouvelle celle-ci tant que le produit est monté.

<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>

Résultat attendu : le fond de carte apparaît et l'onglet Network affiche 200 pour https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions. Le Démarrage rapide propose une page complète par produit.

Depuis un serveur, transmettez une clé serveur avec chaque requête. Cet appel liste les styles de carte connus des endpoints de conception, sans dépenser de crédits IA : c'est un premier test pratique de la clé.

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

Résultat attendu : 200 et un objet JSON contenant un tableau styles. Un 401 avec {"detail":"Invalid or missing API key"} signifie que la valeur est incorrecte ou révoquée. Un 403 avec {"detail":"server_key_in_browser"} indique un en-tête Origin : retirez-le. Poursuivez dans Démarrage rapide côté serveur.

Étapes suivantes

• Démarrage rapide : une page fonctionnelle pour Chat, Viewer et Tile.
• Fonctionnement de Kaleidr : sessions, organisations et les deux quotas d'usage.
• Authentification et scopes : envoi et validation des identifiants.
• Liste de vérification pour la production : une clé par site, origines autorisées et autres préparatifs.