Authentification et portées
Chaque appel à l’API de la plateforme Kaleidr comporte un identifiant d’accès. Il en existe trois types, que l’API traite différemment :
- Une clé publiable identifie votre organisation dans le navigateur. Elle ne peut pas appeler l’API directement : elle est échangée contre une session.
- Un jeton de session est l’identifiant réellement utilisé par le navigateur pour appeler l’API. Il a une durée de vie limitée et est lié à une origine web ainsi qu’à un produit.
- Une clé serveur est un secret que votre backend envoie directement à chaque requête.
Cette page explique comment transmettre chaque identifiant, comment se déroule l’échange, ce que permettent les portées, comment obtenir la portée vendor ainsi que chaque erreur d’authentification, sa cause et sa solution. Pour connaître les risques en cas de fuite d’un identifiant, consultez le modèle de sécurité.
Types d’identifiants
| Identifiant | Préfixe | Emplacement | Utilisation | Offre |
|---|---|---|---|---|
| Clé publiable | kld_pk_live_… | Code source de la page | Envoyée une fois lors de l’échange de session ; refusée sur tous les autres endpoints | Free, Pro, Enterprise |
| Jeton de session | kld_sess_live_… | Mémoire du navigateur | Envoyé à chaque appel d’exécution depuis la page pour laquelle il a été émis | Émis à partir d’une clé publiable ou d’une carte publiée |
| Clé serveur | kld_sk_live_… | Uniquement sur votre backend | Envoyée à chaque appel d’exécution ; refusée si la requête comporte un en-tête Origin | Pro, Enterprise |
| Ancienne clé | kld_live_… | Votre backend | Fonctionne comme identifiant direct, à l’image d’une clé serveur. Sa rotation produit une clé serveur | Uniquement les clés existantes |
Les clés créées via l’API de gestion des clés avec environment: "test" comportent test au lieu de live (kld_pk_test_…, kld_sk_test_…). Une clé de test ne permet pas de charger les tuiles de fond de carte.
Une clé n’est affichée intégralement qu’une seule fois, lors de sa création ou de sa rotation. Kaleidr ne conserve qu’une empreinte cryptographique : une clé perdue ne peut pas être récupérée. Vous devez la remplacer par rotation.
Transmettre un identifiant
Envoyez l’identifiant dans l’un ou l’autre des en-têtes. Les deux sont acceptés par tous les endpoints.
Authorization: Bearer kld_sk_live_…
X-Api-Key: kld_sk_live_…
Si une requête contient les deux, Authorization est utilisé lorsque sa valeur commence par un préfixe Kaleidr ; sinon, X-Api-Key est lu. Ne placez jamais une clé serveur dans une URL.
Ce que chaque identifiant peut faire sur un endpoint d’exécution (tous les endpoints sauf celui de l’échange de session) :
| Identifiant | Résultat sur un endpoint d’exécution |
|---|---|
| Clé publiable | 401 publishable_requires_session. Effectuez d’abord l’échange. |
Clé serveur sans en-tête Origin | Acceptée, puis vérification de la liste des adresses IP autorisées, des portées, des produits autorisés, du quota et de la limite de débit. |
Clé serveur avec en-tête Origin | 403 server_key_in_browser. Les navigateurs ajoutent Origin aux requêtes intersites ; l’API peut ainsi reconnaître une clé serveur utilisée depuis une page web. |
| Jeton de session provenant de son origine d’émission | Accepté. |
Jeton de session avec un autre Origin | 403 session_origin_mismatch. |
Jeton de session d’une carte publiée sans Origin | 403 session_origin_mismatch. |
Le SDK JavaScript applique cette règle en amont : Kaleidr.mount refuse une clé kld_sk_… dans le navigateur sans envoyer de requête.
Échange de session
Une clé publiable est échangée contre un jeton de session auprès d’un endpoint. Le SDK effectue cet échange à chaque montage utilisant une clé et renouvelle le jeton ; vous ne devez l’appeler directement que si vous développez votre propre client navigateur.
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
X-Api-Key: kld_pk_live_…
Content-Type: application/json
{ "product": "chat" }
Le champ product est obligatoire et doit valoir chat, editor, viewer ou tile. La requête doit comporter un en-tête Origin. Un navigateur l’ajoute automatiquement.
{
"session_token": "kld_sess_live_eyJhbGciOi…",
"expires_in": 900,
"product": "chat",
"basemap_style_id": null
}
| Champ | Signification |
|---|---|
session_token | Identifiant utilisé pour les appels d’exécution. Format kld_sess_{env}_{token}. |
expires_in | Durée de validité en secondes. Une session avec clé dure 900 secondes. Lisez ce champ ; ne codez pas cette valeur en dur. |
product | Produit auquel la session est liée. |
basemap_style_id | Fond de carte par défaut de votre organisation, ou null si aucun n’est défini. |
Éléments auxquels une session est liée
- Une origine. Le
Originde la requête d’échange. Tout appel provenant d’une autre origine est refusé. - Un produit. Une session
tilene peut pas appeler les endpoints de chat. - Un ensemble restreint de portées. La session ne possède que la portée nécessaire à son produit :
aipour chat,designpour editor,mapspour tile, aucune pour viewer. Une session de chat conserve égalementvendorsi la clé la possède et que votre offre l’autorise (Enterprise). Aucun autre produit ne peut recevoirvendordans sa session.
Renouvellement
Un client ne peut pas demander une durée de validité supérieure. Effectuez un nouvel échange avant l’expiration indiquée par expires_in. Le SDK renouvelle la session 90 secondes avant l’expiration, lorsqu’un onglet en arrière-plan redevient visible et que la session expire dans les 90 secondes ou a déjà expiré, puis toutes les 30 secondes après un échec de renouvellement. Si le premier échange échoue, le montage échoue et n’est pas réessayé.
Chaque échange avec product: "tile" consomme un chargement de carte du quota de votre organisation ; les autres produits ne coûtent rien à l’échange. L’échange dispose de sa propre limite de débit par clé, distincte des appels d’exécution. Consultez Quotas et limites de débit.
Ordre des vérifications
L’échange s’arrête à la première vérification qui échoue :
| Ordre | Vérification | Échec |
|---|---|---|
| 1 | La clé est valide | 401 Invalid or missing API key |
| 2 | Limite de débit des échanges de la clé | 429 rate_limited |
| 3 | Il s’agit d’une clé publiable | 403 publishable_key_required |
| 4 | La requête comporte un en-tête Origin | 403 origin_required |
| 5 | L’origine figure dans les origines autorisées de la clé, si une liste existe | 403 origin_not_allowed |
| 6 | Les restrictions de la clé n’excluent pas ce produit | 403 product_not_allowed |
| 7 | Votre offre comprend ce produit | 403 tier_capability_not_allowed |
| 8 | La clé détient la portée requise par le produit | 403 insufficient_scope, ou tier_capability_not_allowed si la clé la détient, mais que votre offre ne l’inclut plus |
| 9 | Pour tile : un chargement de carte est encore disponible | 429 map_load_quota_exceeded |
Essai depuis un terminal
curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "X-Api-Key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "Content-Type: application/json" \
-d '{"product":"chat"}'
Cela fonctionne parce que Origin est un en-tête ordinaire qu’un client hors navigateur peut définir librement. C’est pourquoi la liste des origines autorisées est décrite comme un contrôle destiné aux navigateurs, et non comme un secret : consultez CORS et origines autorisées.
Sessions pour une carte publiée
Une carte publiée depuis Studio dont la tuile Kaleidr AI active Control Tower ou Popup Window peut proposer le chat à ses visiteurs sans clé dans la page. La page échange à la place l’identifiant public de la carte, ainsi que la fonctionnalité qu’elle ouvre :
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions
Content-Type: application/json
{ "share_id": "your-map-id", "feature": "control_tower" }
{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }
Cette session ne permet que le chat, comporte la portée ai, dure 300 secondes et est facturée à l’organisation propriétaire de la carte. Elle ne contient jamais vendor. Elle doit être utilisée depuis la page qui l’a demandée : un appel sans Origin ou avec une autre origine est refusé. Les motifs de refus sont :
| Statut | Code | Cause |
|---|---|---|
| 403 | origin_required | La requête ne comporte pas d’en-tête Origin. |
| 404 | not_found | Aucune carte publiée ni aucun lien de partage ne possède cet identifiant, ou la carte du lien de partage est dépubliée. |
| 403 | chat_disabled | La Kaleidr AI de la carte n’active pas la fonctionnalité demandée. |
| 403 | origin_not_allowed | La page ne figure pas parmi les domaines autorisés de la carte. |
| 403 | owner_has_no_organization | Le propriétaire de la carte ne possède pas d’organisation à facturer. |
| 403 | tier_capability_not_allowed | L’offre du propriétaire ne comprend pas le chat. |
| 429 | rate_limited | Trop d’échanges pour cette carte ou depuis cette adresse. |
La configuration est décrite dans Kaleidr AI sur une carte publiée.
Portées
Chaque clé possède des portées. Chaque famille d’endpoints en exige une.
| Portée | Autorise | Nécessaire pour |
|---|---|---|
ai | Endpoints /chat/* et /retrieval/* | Chat et tout backend appelant les endpoints de chat ou de recherche |
design | Endpoints /design/* | Sessions Editor et tout backend appelant les endpoints de conception |
maps | Sessions de fond de carte | Tile |
vendor | Rien à elle seule. Elle permet aux réponses de chat d’utiliser les données publiées par votre organisation. | Chat, lorsque vous avez importé des données |
Une nouvelle clé reçoit ai, maps et design, sauf demande contraire. Avec l’offre Free, une clé comporte toujours toutes les fonctionnalités Free : exactement ces trois portées et les quatre produits (chat, editor, viewer, tile), quel que soit le produit demandé. vendor n’est jamais attribuée par défaut ; seule une organisation Enterprise peut créer une clé dotée de cette portée.
Une demande de création de clé mentionnant une portée ou un produit non disponible dans votre offre est refusée avec 403 tier_capability_not_allowed. Rien n’est retiré silencieusement de la demande. En pratique, cela concerne les demandes de vendor sous Free ou Pro.
Les portées sont fixées lors de la création de la clé. Aucun endpoint ni paramètre ne permet de les modifier ensuite. Une clé issue d’une rotation les hérite, à l’exception de celles que votre offre actuelle n’autorise plus. Pour modifier les portées d’une clé, créez-en une nouvelle et révoquez l’ancienne.
La rotation sous Free suit la règle Free. Dans l’offre Free, le remplacement d’une clé publiable par rotation comprend toutes les fonctionnalités Free (ai, maps, design et les quatre produits), quelles que soient les portées précédentes. Il est impossible d’effectuer la rotation d’une clé serveur ou d’une ancienne clé sous Free : la requête est refusée avec 403 free_plan_publishable_only.
Les capacités d’une clé sont limitées à la fois par la clé et par l’offre
À chaque requête, les portées et produits enregistrés sur la clé sont comparés à ceux inclus dans l’offre de votre organisation au moment de la requête. Changer d’offre ne modifie jamais une clé, mais change ce qu’elle peut faire :
insufficient_scope: la clé n’a jamais reçu cette portée. Solution : utiliser une clé qui la possède.tier_capability_not_allowed: la clé possède cette portée, mais votre offre actuelle ne la comprend pas. Solution : changer d’offre.
vendor fait exception au deuxième cas, car elle ne donne accès à aucun endpoint. Une clé contenant vendor dans une offre inférieure à Enterprise n’est pas refusée : ses requêtes aboutissent, mais les réponses sont générées sans vos données.
Une clé dont la liste de produits est vide peut utiliser tous les produits inclus dans votre offre. Une clé sans aucune portée est refusée partout.
Une limitation de produits s’applique à toutes les clés
allowed_products limite une clé à certains produits parmi chat, editor, viewer et tile. La limitation s’applique à chaque type de clé, au moment où elle est utilisée :
| Clé | Où la limitation est vérifiée | Refus |
|---|---|---|
| Clé publiable | Lors de l’échange de session, selon le product demandé | 403 product_not_allowed |
| Clé serveur ou ancienne clé | À chaque requête d’exécution, selon le produit auquel appartient l’endpoint | 403 product_not_allowed |
Chaque famille d’endpoints appartient au produit qui a besoin de sa portée :
| Endpoints | Portée | Produit que doit autoriser une clé limitée |
|---|---|---|
/chat/*, /retrieval/* | ai | chat |
/design/* | design | editor |
Ainsi, une clé serveur créée avec "allowed_products": ["tile"] est refusée sur /chat/control/stream avec 403 product_not_allowed, même si elle possède la portée ai. Une clé serveur limitée à viewer ne peut appeler aucun endpoint d’exécution, puisqu’une carte publiée ne nécessite pas de clé. Laissez la liste vide lorsqu’une clé doit accéder à tous les endpoints autorisés par ses portées.
Un jeton de session n’est pas vérifié de nouveau ici : il a déjà été lié à un seul produit lors de l’échange.
| Free | Pro | Enterprise | |
|---|---|---|---|
| Clés publiables | Oui | Oui | Oui |
| Clés serveur | Non | Oui | Oui |
ai, maps, design | Oui | Oui | Oui |
vendor | Non | Non | Oui |
Pro ajoute les clés serveur et augmente la limite de clés actives par rapport à Free. Le tableau complet des offres figure dans Obtenir une clé API.
La portée vendor
vendor ne donne accès à aucun endpoint. Elle détermine si une réponse de chat produite avec cette clé peut s’appuyer sur les données publiées par votre organisation, en plus des connaissances générales de Kaleidr. Le parcours complet, de l’importation à la réponse, est décrit dans Vos données : présentation.
Qui peut l’utiliser :
- Les offres Free et Pro ne peuvent pas inclure
vendor. La création d’une clé qui la demande est refusée avec 403tier_capability_not_allowed, quevendor_acknowledgedsoit fourni ou non. Aucune clé n’est créée. - Les organisations Enterprise peuvent créer des clés dotées de
vendor.
Cette portée sert à lire des données au moyen d’une clé. Leur importation nécessite une autorisation distincte, détenue par un propriétaire ou un administrateur de l’organisation et non par une clé ; elle est également réservée à Enterprise : Free et Pro ne peuvent pas importer de données métier. Les fichiers qu’un utilisateur connecté ajoute à une carte dans Kaleidr Studio relèvent d’une autre fonctionnalité, disponible dans toutes les offres, et aucune portée ne permet de les lire : consultez Jeux de données sur une carte.
La page API Keys ne peut pas accorder vendor. Créez la clé via l’API de gestion des clés :
curl -s https://api.kaleidr.com/shared-api/api-keys \
-H "Authorization: Bearer $KALEIDR_ACCOUNT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "store-locator-chat",
"key_type": "publishable",
"scopes": ["ai", "vendor"],
"vendor_acknowledged": true,
"allowed_origins": ["https://www.example.com"]
}'
vendor_acknowledged: true est obligatoire pour une clé publiable qui possède vendor. En son absence, la requête échoue avec 422 vendor_scope_requires_acknowledgement. Ce champ existe parce qu’une clé publiable apparaît dans le code source public de la page : les données auxquelles elle donne accès peuvent donc être consultées par n’importe quel visiteur. Une clé serveur ne nécessite aucune confirmation.
Avant d’ajouter vendor à une clé publiable :
- Utilisez une clé par site web. Seul le site qui doit répondre à partir de vos données doit posséder
vendor. - Considérez toutes les données publiées sur ce site comme publiques. Ne publiez pas vos coûts d’achat, tarifs non annoncés ni aucune information que vous n’afficheriez pas sur la page.
- N’oubliez pas que les sessions déjà ouvertes n’obtiennent pas cette portée. Une clé créée avec
vendorne la transmet qu’aux sessions échangées par la suite.
Pour retirer vendor, révoquez la clé et créez une clé de remplacement sans cette portée. La révocation prend effet dès la requête suivante, y compris pour les sessions déjà émises.
Lorsqu’une organisation quitte Enterprise
Passer d’Enterprise à Pro ou Free ne modifie pas vos clés et ne provoque pas leur échec :
| Élément | Après le changement |
|---|---|
Une clé contenant vendor | Continue à fonctionner pour toutes les autres fonctions. Ses réponses n’utilisent plus vos données. Aucun message d’erreur, état ou champ ne le signale. |
| Sessions navigateur émises avant le changement | Elles prennent fin. Leur prochaine requête renvoie 401, et le SDK obtient une nouvelle session sans vendor. |
Rotation d’une clé contenant vendor | Sous Pro : réussite avec 201. La clé de remplacement conserve les mêmes portées sans vendor ; sa liste de produits ne change pas. Sous Free : le remplacement d’une clé publiable comprend ai, maps, design et les quatre produits, quels que soient les droits précédents ; la rotation d’une clé serveur ou ancienne est refusée avec 403 free_plan_publishable_only. |
Création d’une clé avec vendor | Refusée avec 403 tier_capability_not_allowed. |
| Vos versions publiées | Les propriétaires et administrateurs peuvent toujours les répertorier, annuler leur publication et les supprimer, quelle que soit l’offre, via l’API d’importation. Sous Free et Pro, l’importation et la publication sont refusées avec 403 vendor_data_not_on_plan. |
Si vous revenez à Enterprise, une clé qui possède encore vendor retrouve l’accès aux données. Une clé de remplacement créée par rotation sous une offre inférieure ne récupère pas cette portée : créez une nouvelle clé.
Restreindre une clé
| Restriction | S’applique à | Réglage dans API Keys | Réglage via l’API de gestion des clés | Refus |
|---|---|---|---|---|
| Origines autorisées | Clés publiables | Oui | Oui (allowed_origins) | 403 origin_not_allowed lors de l’échange |
| Produits autorisés | Toutes les clés | Non | Oui (allowed_products) | 403 product_not_allowed : lors de l’échange pour une clé publiable ; à chaque appel d’exécution pour une clé serveur ou ancienne. Consultez limitations de produits. |
| Liste d’adresses IP autorisées | Clés serveur et anciennes | Non | Oui (allowed_ips) | 403 ip_not_allowed |
| Plafond mensuel | Toutes les clés | Non | Oui (monthly_cap_tokens) | 429 quota_exceeded |
| Expiration | Toutes les clés | Non | Oui (expires_at) | 401 après cette date |
| Portées | Toutes les clés | Non | Uniquement à la création (scopes) | 403 insufficient_scope |
Origines autorisées. Jusqu’à 100 entrées, chacune au format scheme://host[:port], sans chemin. Une liste vide sur une clé publiable autorise toutes les origines. Les détails et les causes d’échec sont expliqués dans CORS et origines autorisées.
Liste d’adresses IP autorisées. Jusqu’à 100 adresses IP ou blocs CIDR. Un bloc couvrant toutes les adresses (/0) est refusé : laissez la liste vide pour autoriser « toutes les adresses ». Si une clé comporte une liste et que l’adresse de l’appelant ne peut pas être déterminée, la requête est refusée.
Plafond mensuel. Limite des crédits d’IA de votre organisation que cette clé peut consommer pendant une période de facturation. Consultez Quotas et limites de débit.
Effets sur une session déjà émise
À chaque requête, une session relit sa clé parente : la suppression d’un accès prend donc rapidement effet. L’ajout d’un accès nécessite un nouvel échange.
| Modification de la clé ou du compte | Effet sur une session d éjà émise |
|---|---|
| Clé révoquée ou remplacée sans délai de grâce | 401 à sa prochaine requête. |
| Origine de la session retirée des origines autorisées de la clé | 401 à sa prochaine requête. |
| Produit de la session retiré des produits autorisés de la clé | 401 à sa prochaine requête. |
| Passage à une offre inférieure | Les sessions émises avant le changement reçoivent 401. Les sessions échangées après reçoivent 403 tier_capability_not_allowed pour ce que l’offre n’inclut plus. |
| Ajout ou diminution d’un plafond mensuel | Applicable dès la prochaine requête. |
| Suppression du plafond mensuel | Applicable à partir du prochain échange. |
| Passage à une offre supérieure | Applicable à partir du prochain échange. |
Une session ne durant que quelques minutes, « à partir du prochain échange » représente un court délai. Le renouvellement du SDK applique le changement sans modification du code.
API de gestion des clés
La page API Keys sur kaleidr.com/api-keys permet de définir le nom d’une clé, son type et ses origines autorisées. Tous les autres réglages décrits ici passent par la même API que cette page.
- URL de base :
https://api.kaleidr.com/shared-api/api-keys - Authentification :
Authorization: Beareravec le jeton d’accès d’un compte Kaleidr connecté appartenant à un propriétaire ou administrateur de l’organisation. Une clé de plateforme n’est pas acceptée ici. Il n’existe actuellement aucun identifiant longue durée distinct pour gérer les clés. - Organisation : sans organisation indiquée, votre organisation principale est utilisée. Pour en désigner une autre, envoyez
org_iddans le corps JSON lors de la création d’une clé et comme paramètre de requête?org_id=sur toutes les autres routes. Le paramètreorg_iddans l’URL de création est ignoré.
| Méthode et chemin | Fonction | Réussite |
|---|---|---|
POST / | Créer une clé | 201, objet de la clé et plaintext_key |
GET / | Répertorier les clés actives, des plus récentes aux plus anciennes | 200 |
GET /{id}/events?limit=1..200 | Événements d’audit d’une clé | 200 |
PATCH /{id} | Modifier les restrictions | 200, objet de la clé |
POST /{id}/rotate | Remplacer la clé | 201, nouvelle clé et plaintext_key |
POST /{id}/revoke | Révoquer la clé | 200, objet de la clé |
Aucune route de suppression n’existe : révoquez une clé pour la retirer.
Champs acceptés lors de la création d’une clé :
| Champ | Type | Valeur par défaut | Remarques |
|---|---|---|---|
name | chaîne de 1 à 200 caractères | obligatoire | |
org_id | UUID | votre organisation principale | Organisation dans laquelle la clé est créée. Envoyé dans le corps : le paramètre de requête est ignoré sur cette route. |
key_type | "publishable" ou "server" | "publishable" | "server" est refusé sous Free avec 403 free_plan_publishable_only. |
environment | "live" ou "test" | "live" | |
scopes | tableau de chaînes | ["ai", "maps", "design"] | Parmi ai, maps, design, vendor. Toute autre valeur entraîne 422 unknown_scope. Une portée non autorisée par votre offre (vendor sous Enterprise) entraîne 403 tier_capability_not_allowed. |
allowed_origins | tableau de chaînes, jusqu’à 100 | [] | Sur une clé publiable, une liste vide autorise toutes les origines. |
allowed_products | tableau de chaînes | [] | Parmi chat, editor, viewer, tile. Une liste vide autorise tout. Toute autre valeur entraîne 422 unknown_product. La restriction s’applique aux clés publiables, serveur et anciennes : consultez limitations de produits. |
allowed_ips | tableau de chaînes, jusqu’à 100 | [] | Adresses IP ou blocs CIDR. |
monthly_cap_tokens | entier supérieur ou égal à 0 | aucun | Une valeur d’au moins 1 plafonne la clé. 0 ou null signifie absence de plafond. |
expires_at | date et heure futures | aucun | |
vendor_acknowledged | booléen | false | Obligatoire pour une clé publiable avec vendor (Enterprise). |
PATCH accepte name, allowed_origins, allowed_products, allowed_ips, monthly_cap_tokens et expires_at. Envoyez seulement les champs à modifier ; un null explicite efface une valeur. Il n’accepte pas scopes.
rotate accepte { "grace_hours": 0 }, de 0 à 8760. La nouvelle clé hérite des portées de l’ancienne, sauf celles que l’offre actuelle ne permet plus. Sous Free, elle obtient toujours toutes les fonctionnalités Free, et les clés serveur ou anciennes ne peuvent pas être remplacées par rotation (403 free_plan_publishable_only). Avec 0, l’ancienne clé et ses sessions cessent immédiatement de fonctionner. Avec un délai de grâce, elle continue à fonctionner jusqu’à la fin du délai, compte toujours dans la limite de clés actives de votre offre et ne peut plus être remplacée par rotation. La page API Keys utilise un délai de grâce de 24 heures.
Les erreurs de ces routes sont décrites dans Erreurs : gestion des clés.
Erreurs d’authentification
Un 401 signifie que l’API n’accepte pas l’identifiant. Un 403 signifie qu’elle le reconnaît, mais refuse l’accès. Chaque erreur présente la forme {"detail": "<code>"}.
Dans un navigateur, lorsqu’une requête est refusée à cause de son identifiant ou de son origine, la réponse ne comporte pas d’en-tête CORS : la page voit une erreur CORS, pas le corps de la réponse. Si la requête est refusée plus tard pour une portée ou une offre, la réponse est lisible et le SDK signale kaleidr session exchange failed (403). Dans les deux cas, ouvrez la requête dans l’onglet Network du navigateur pour lire le code. Consultez CORS et origines autorisées.
| Statut | Code | Cause | Solution |
|---|---|---|---|
| 401 | Invalid or missing API key | Aucun identifiant ; clé inconnue, révoquée ou expirée ; session expirée ; session dont la clé a été révoquée, dont l’origine ou le produit n’est plus autorisé, ou émise avant un passage à une offre inférieure ; organisation suspendue ou sans offre. | Vérifiez la valeur et le statut de la clé dans API Keys. Pour une session, effectuez un nouvel échange. |
| 401 | publishable_requires_session | Une clé publiable a été envoyée à un endpoint d’exécution. | Échangez-la contre une session ou appelez depuis un backend avec une clé serveur. |
| 403 | publishable_key_required | L’échange de session a été appelé avec une clé serveur ou ancienne. | Utilisez une clé kld_pk_… pour l’échange. |
| 403 | origin_required | Échange de session sans en-tête Origin. | Appelez depuis une page de navigateur. |
| 403 | origin_not_allowed | L’origine de la page ne figure pas parmi celles autorisées de la clé ou parmi les domaines autorisés de la carte publiée. | Ajoutez l’origine exacte à la clé ou le domaine à la carte. |
| 403 | product_not_allowed | Les produits autorisés de la clé excluent ce produit : le product demandé lors de l’échange ou, pour une clé serveur ou ancienne, le produit auquel appartient l’endpoint appelé. | Modifiez allowed_products ou utilisez une autre clé. |
| 403 | insufficient_scope | La clé a été créée sans la portée nécessaire à cet endpoint ou produit. | Utilisez une clé qui possède cette portée. Les portées ne peuvent pas être modifiées. |
| 403 | tier_capability_not_allowed | La clé possède la portée ou le produit, mais votre offre actuelle ne le comprend pas. | Changez d’offre sur kaleidr.com/billing. |
| 403 | server_key_in_browser | Une clé serveur a été envoyée avec un en-tête Origin. | Déplacez l’appel vers votre backend. Si la clé figurait dans le code source d’une page, remplacez-la par rotation. |
| 403 | session_origin_mismatch | Un jeton de session a été utilisé depuis une origine différente de celle de son émission, ou une session de carte publiée a été utilisée sans Origin. | Échangez une session sur la page qui doit l’utiliser. |
| 403 | ip_not_allowed | Une clé serveur ou ancienne avec liste d’adresses IP autorisées a été utilisée depuis une adresse extérieure à cette liste. | Appelez depuis une adresse autorisée ou modifiez allowed_ips. |
| 403 | chat_disabled | Échange de carte publiée : la Kaleidr AI de la carte n’active pas la fonctionnalité demandée. | Activez Control Tower ou Popup Window dans la tuile Kaleidr AI de la carte dans Studio. |
| 403 | owner_has_no_organization | Échange de carte publiée : le propriétaire de la carte n’a pas d’organisation. | Le propriétaire doit créer ou rejoindre une organisation. |
| 404 | not_found | Échange de carte publiée : aucune carte publiée ni aucun lien de partage ne porte cet identifiant. | Vérifiez l’identifiant et assurez-vous que la carte est publiée. |
Le catalogue complet, y compris les réponses 429 et 5xx, figure dans Erreurs.
Pages associées
- Modèle de sécurité : ce que chaque identifiant permet de faire en cas de fuite.
- CORS et origines autorisées : fonctionnement de la liste des origines.
- Endpoints : endpoints accessibles avec chaque portée.
- Obtenir une clé API : création d’une clé depuis la page API Keys.