Authentification des API cartographiques

Une conception sécurisée sépare les identifiants selon l’environnement d’exécution. Le navigateur a besoin d’un identifiant exposable, strictement limité aux origines et capacités approuvées. Le backend a besoin d’un secret qui n’entre jamais dans le code client et autorise les opérations serveur à serveur. Ils ne doivent pas être interchangeables. Limitez les portées, séparez les environnements, surveillez l’utilisation, faites tourner les identifiants et distinguez échecs d’authentification et d’autorisation. Kaleidr utilise des clés publiables (kld_pk_live_…) et des clés serveur (kld_sk_live_…).

Les sections suivantes couvrent identifiants navigateur et serveur, origines, CORS, portées, cycle de vie, limites de confiance multitenant et erreurs courantes. Consultez la documentation développeur. Pour l’architecture SDK, voir Qu’est-ce qu’un SDK cartographique d’IA ?. Pour l’intégration et les montages de chat, voir Intégrer une carte interactive et Chat IA sur Mapbox, Google Maps et MapLibre.

Principes essentiels

• L’environnement d’abord : les identifiants navigateur sont conçus pour être exposés ; ceux du serveur pour rester secrets.
• Origine ≠ authentification : CORS et les origines autorisées ne remplacent pas la vérification.
• Portée ≠ locataire : les portées d’API ne sont pas l’autorisation d’un utilisateur ou d’une ligne.
• Rotation sûre : déployez un remplacement avant de révoquer une clé active.
• Expurgez les journaux : consignez ID et codes d’état, jamais les valeurs.

Pourquoi l’authentification est-elle différente dans le navigateur ?

Le navigateur est un environnement non fiable. Tout ce qui lui est livré peut généralement être inspecté dans la source, les outils développeur, les requêtes réseau, le JavaScript groupé, le stockage ou les objets d’exécution. Mettre un secret serveur durable dans le client—source React, variables Next.js NEXT_PUBLIC_*, Vite VITE_*, HTML, webviews mobiles ou JSON frontend—est dangereux, car le navigateur ne peut le cacher à son utilisateur. Demandez ce que l’identifiant peut faire et où il peut s’exécuter, pas où le dissimuler dans un bundle.

Les noms varient, mais le modèle est courant. Kaleidr distingue clés publiables et serveur (Auth & Scopes). Mapbox distingue les portées publiques et secrètes et exige que les requêtes à jeton secret viennent d’un serveur (Utiliser Mapbox en sécurité). Google Maps Platform combine restrictions d’application et d’API et recommande de protéger les identifiants de services Web, avec OAuth 2.0 lorsque pris en charge entre serveurs (Conseils de sécurité). Les identifiants client doivent être exposables ; les identifiants serveur doivent rester secrets.

Comment fonctionnent les clés Kaleidr ?

La documentation actuelle définit deux formes de clés dans le même système d’organisation et de capacités. Les clés publiables utilisent kld_pk_live_… dans HTML, le SDK, <kaleidr-map> et les intégrations navigateur. Le SDK les échange à l’exécution contre une session brève liée à l’origine, plutôt que d’utiliser la chaîne comme bearer permanent. Les clés serveur kld_sk_live_… restent sur des serveurs fiables, généralement dans Authorization: Bearer … ou X-Api-Key: …. Elles sont bloquées dans le navigateur et ne reçoivent aucune autorisation CORS (CORS & Allowed Origins). Ne mettez jamais une clé serveur dans le client et ne considérez pas une variable frontend publique comme stockage secret.

Les origines autorisées doivent être nues, sans chemin ni barre finale : https://app.example.com, pas https://app.example.com/maps. Kaleidr exige HTTPS sauf pour les tests locaux sur localhost ou 127.0.0.1. La correspondance exacte compte : racine, www, app, admin et prévisualisation sont des origines distinctes. Ces restrictions réduisent la réutilisation illicite, mais ne remplacent pas la protection des secrets serveur.

Quelle différence entre CORS, authentification, portée et autorisation ?

CORS décide si un navigateur peut lire une réponse interorigine. L’authentification identifie l’appelant. La portée détermine si l’identifiant peut utiliser une capacité. L’autorisation de l’application hôte décide quel utilisateur ou locataire accède aux enregistrements privés. Kaleidr peut accepter un preflight, mais ne renvoie Access-Control-Allow-Origin que pour une origine autorisée ; les clés serveur n’obtiennent aucun droit CORS. 401 signale généralement un identifiant absent, invalide, expiré ou révoqué. 403 signale un identifiant valide sans permission ; Kaleidr renvoie insufficient_scope si la capacité requise manque. Distinguez-les dans les diagnostics et la surveillance.

Comment créer, stocker, faire tourner et révoquer les identifiants ?

Appliquez le moindre privilège : n’accordez que les portées nécessaires. Mapbox recommande les portées minimales et seulement publiques dans le navigateur ; Google recommande des restrictions d’application et d’API limitées à celles réellement utilisées. Ne partagez pas un identifiant entre développement, prévisualisation et production. Des clés séparées réduisent le rayon d’impact et sécurisent la rotation. Mapbox recommande des jetons distincts par environnement ou client ; Google des clés distinctes par application (Gestion des jetons).

Les nouvelles valeurs Kaleidr ne sont montrées qu’une fois : copiez-les aussitôt dans un gestionnaire de secrets. Stockez les clés serveur dans un gestionnaire ou environnement protégé, jamais dans un dépôt public ou bundle navigateur. Dans CI/CD, injectez au déploiement, masquez dans les journaux et n’imprimez pas les variables d’environnement. Consignez ID, état et origine ; expurgez en-têtes d’autorisation et valeurs. Pour la rotation, créez et restreignez un remplacement, déployez, vérifiez le trafic puis révoquez l’ancienne clé—plus vite en cas de compromission. Les quotas sont aussi un contrôle : l’usage est mesuré par organisation et le streaming limite la concurrence (Quota & Rate Limits). Traitez 429 différemment de 401 et 403 ; appliquez un délai progressif.

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

Comment séparer l’authentification de plateforme de celle de l’hôte ?

Le modèle recommandé utilise dans le navigateur une clé publiable pour les fonctions cartographiques publiques via une origine approuvée, tandis que les requêtes produit authentifiées vont au backend. Celui-ci gère identité, appartenance au locataire, autorisation d’objets, données privées et clé serveur dans un gestionnaire de secrets, appelle la plateforme entre serveurs et ne renvoie que les champs approuvés. Une clé publiable n’authentifie pas l’utilisateur final ; une clé serveur n’autorise pas les lignes de base de données. Selon la documentation, une carte Viewer publiée est protégée par lien de partage et ne nécessite pas de clé. Traitez néanmoins le lien comme contrôle d’accès et n’envoyez pas de données privées via une vue publique sans restriction. CSP et le rendu HTML sûr sont complémentaires ; Mapbox avertit que du HTML non fiable dans une popup peut créer une faille XSS et recommande le rendu texte.

Quelles erreurs éviter ?

En cas d’échec navigateur, vérifiez orthographe de l’origine, HTTPS, type de clé, portée et ordre d’échange avant d’accuser la plateforme. Côté serveur, vérifiez type, environnement, portée, injection du secret et révocation accidentelle.

Verdict final

La sécurité commence par une décision : ne pas employer le même modèle d’identifiants dans le navigateur et le backend. Le navigateur exige des identifiants exposables limités par origine, portée, durée de session ou contrôles équivalents ; le backend exige des secrets dans une infrastructure fiable. Ajoutez moindre privilège, isolation, autorisation applicative, surveillance et rotation. Kaleidr suit ce modèle : les clés publiables sont limitées par origine et échangées contre des sessions brèves ; les clés serveur sont des bearer pour les appels serveur à serveur et sont bloquées dans le navigateur. Cette frontière importe davantage que tenter de cacher une clé dans le frontend.

Sécurisez votre API avec la documentation Kaleidr

Vérifiez types de clés, portées, règles d’origine et comportement avant déploiement. Lire Kaleidr Auth & Scopes, puis consultez la documentation développeur pour les montages SDK et routes de Platform API.

FAQ

Qu’est-ce que l’authentification d’une API cartographique ?

Le mécanisme qui identifie l’application ou le service demandant l’accès à des API de cartes, lieux, tuiles, itinéraires ou données spatiales. Les mécanismes courants sont clés, jetons d’accès, sessions, bearer et OAuth.

Une clé API peut-elle être utilisée dans un navigateur ?

Seulement si le fournisseur la conçoit pour le client. Elle doit être limitée par origine, portée publique, application ou échange de session brève. Un secret serveur ne doit jamais figurer dans le navigateur.

Une clé publiable est-elle secrète ?

Non. Sa sécurité ne doit pas dépendre du masquage de la chaîne, mais elle exige restrictions et surveillance.

Une clé serveur est-elle secrète ?

Oui. Elle doit rester dans le backend fiable et ne pas apparaître dans HTML, bundles JavaScript, webviews, dépôts publics ou stockage client.

CORS est-il une authentification ?

Non. CORS contrôle la lecture des réponses interorigine ; l’authentification identifie l’appelant et l’autorisation détermine ses droits.

Quelle différence entre 401 et 403 ?

401 indique généralement un identifiant absent, invalide, expiré ou révoqué. 403 indique généralement un identifiant valide sans permission.

Faut-il séparer les clés de développement et production ?

Oui. Cela réduit le rayon d’impact, simplifie les restrictions, améliore la visibilité et sécurise la rotation.

Comment faire tourner une clé API ?

Créez et limitez un remplacement, déployez-le, vérifiez le trafic puis révoquez l’ancienne clé. Accélérez en cas de compromission active.

Kaleidr Viewer exige-t-il une clé API ?

La documentation actuelle indique que les cartes Viewer publiées sont protégées par lien de partage et n’exigent pas de clé.

Comment Kaleidr protège-t-il les intégrations navigateur ?

Une clé publiable possède une liste d’origines ; le SDK l’échange contre une session brève liée à l’origine. Les clés serveur sont bloquées dans le navigateur et réservées aux appels serveur.

Références

• IETF. HTTP Semantics (RFC 9110). RFC Editor. Consulté le 17 août 2026. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. Consulté le 17 août 2026. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. Consulté le 17 août 2026. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google. Conseils de sécurité Google Maps Platform. Documentation Google Maps Platform. Consulté le 17 août 2026. https://developers.google.com/maps/api-security-best-practices

• Kaleidr. Auth & Scopes. Documentation développeur Kaleidr. Consulté le 17 août 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr. CORS & Allowed Origins. Documentation développeur Kaleidr. Consulté le 17 août 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr. Quota & Rate Limits. Documentation développeur Kaleidr. Consulté le 17 août 2026. https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox. Utiliser Mapbox en sécurité. Documentation Mapbox. Consulté le 17 août 2026. https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox. Gestion des jetons. Documentation Mapbox. Consulté le 17 août 2026. https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}