Les clés d'API · Aide de Measure Map Online

Créez la clé qui relie votre site web ou votre logiciel à Measure Map Online, choisissez ce qu'elle peut faire, séparez la production des tests, et remplacez-la ou restreignez-la en toute sécurité.

Une clé d'API permet à votre propre site web ou logiciel de travailler avec votre compte Measure Map Online : afficher la carte d'un projet sur votre site, démarrer des projets pour vos visiteurs, ou lire et modifier des projets via l'API REST. Vous créez et gérez les clés sur la page Développeur.

Ouvrir la page Développeur#

Dans le menu du tableau de bord, sous Avancé, appuyez sur Développeur. Elle s'ouvre sur Clés d’API, et ses autres sections sont listées en dessous dans le menu (sur un téléphone, sous forme d'onglets en haut de la page) :

Lien invité (Open Guest) : le lien sans code pour votre site web. Voir Open Guest.
Essayer l’API, Webhooks et API REST : voir la référence de l'API.
Intégrer une carte (Enterprise) : voir l'API iFrame.

Le badge en haut de l'encadré de la clé indique si votre clé est Actif, Non activé (pas encore de clé), Désactivé (accès à l'API suspendu : aucune clé ne fonctionne et aucune nouvelle ne peut être créée tant que l'assistance n'a pas levé la suspension) ou Expiré (l'abonnement n'est pas actif).

La section Clés d'API avec une clé sandbox, ce qu'elle peut faire et les boutons pour l'afficher et la copier

Production et bac à sable#

En haut de l'encadré de la clé, passez de Production à Bac à sable et inversement. Chacun a sa propre clé, et la page affiche celle que vous choisissez. Ce choix s'applique aussi dans Essayer l’API, et il est conservé quand vous passez d'une section à l'autre. Intégrer une carte et Lien invité utilisent toujours votre clé de production, car les visiteurs de votre site web ne peuvent ouvrir que des projets de production : ouvrir l'une de ces sections ramène la page sur Production.

Production est votre vrai compte, et la page s'ouvre dessus. Utilisez une clé de production sur votre site web.
Bac à sable sert à construire et à tester une intégration. Les projets, dossiers et produits créés avec une clé de bac à sable sont tenus à l'écart des vrais : une clé de production ne les voit pas, et une clé de bac à sable ne voit pas vos données de production. Les requêtes faites avec une clé de bac à sable ne comptent pas dans vos chiffres d'utilisation, et les projets invités créés avec une telle clé ne sont jamais facturés.

Créer une nouvelle clé de bac à sable n'affecte jamais votre clé de production, et inversement.

Choisir ce que la clé peut faire#

Sous Accès de la nouvelle clé, chaque ligne correspond à un domaine de l'API. Choisissez jusqu'où la prochaine clé que vous créerez pourra y accéder :

Domaine	Choix	Ce qu'il permet
Cartes intégrées	Aucun accès, Autorisé	Connecter un visiteur à une carte intégrée. La plupart des intégrations n’ont besoin que de cela.
Projets	Aucun accès, Lecture, Lecture et modification	Projets et dossiers, avec leurs mesures, commentaires et exports.
Utilisateurs (Enterprise)	Aucun accès, Lecture, Lecture et modification	Les personnes de votre compte et leurs sièges.
Produits	Aucun accès, Lecture, Lecture et modification	Votre catalogue de produits et ses tarifs.

Maintenez le pointeur sur un choix pour voir exactement ce qu'il accorde. Votre première clé démarre avec Cartes intégrées seulement, ce qui suffit à une carte intégrée ; une clé qui en remplace une autre démarre avec l'accès de cette clé. Choisissez au moins un domaine. Se connecter en tant que l'un des membres de votre organisation via l'API nécessite Utilisateurs : Lecture et modification, et non Cartes intégrées.

Ce qu'une clé peut faire est fixé à sa création. Pour donner à une clé plus ou moins d'accès, créez-en une nouvelle.

L'accès de la nouvelle clé, une ligne par domaine de l'API

Créer une clé#

Choisissez Production ou Bac à sable.
Réglez l'accès sous Accès de la nouvelle clé.
Si vous le souhaitez, saisissez un nom dans Nom de la nouvelle clé (facultatif), pour distinguer vos clés.
Appuyez sur Générer une nouvelle clé.

La clé apparaît sous Votre clé d’API, masquée sauf ses premiers et derniers caractères, avec une ligne qui indique ses Autorisations. Appuyez sur pour l'afficher en entier, ou sur pour copier la clé complète. Vous recevez un e-mail chaque fois qu'une clé est créée sur votre compte.

Une clé créée avant l'existence des domaines d'accès peut tout faire, sauf travailler avec les produits et se connecter en tant que membre ; l'encadré vous en avertit. Remplacez-la par une clé plus restreinte si vous ne l'utilisez que pour des intégrations.

Remplacer une clé#

Appuyez de nouveau sur Générer une nouvelle clé quand vous avez déjà une clé. L'application vous prévient d'abord : Une nouvelle clé sera créée et votre clé actuelle continuera de fonctionner pendant 24 heures, le temps de mettre à jour les sites qui l’utilisent. Vous pouvez la révoquer plus tôt une fois terminé.

L'ancienne clé passe dans Clés précédentes, avec le temps qu'il lui reste et la date de sa dernière utilisation. Toujours acceptées pendant le déploiement de la nouvelle clé. Révoquez-la dès que plus rien ne l’utilise. Pour l'arrêter immédiatement, appuyez sur Révoquer et confirmez ; tout site qui l'utilise encore cesse aussitôt de fonctionner. Vous recevez un e-mail quand une clé est révoquée.

Vos restrictions de site web sont copiées sur la nouvelle clé. Vous pouvez créer une nouvelle clé environ une fois par minute.

Une clé précédente encore acceptée pendant quelques heures, avec son bouton Révoquer

Limiter la clé à vos sites web#

Seuls les sites de cette liste peuvent utiliser votre clé dans un navigateur : les cartes intégrées et les requêtes envoyées depuis les pages de tout autre site sont refusées. Les appels depuis un serveur ne sont pas concernés.

Sous Restrictions du site web, saisissez votre site dans Entrer un site web ou un domaine : un domaine comme example.com, une adresse IP ou localhost. Vous pouvez coller une adresse complète : seul le nom du site est conservé, sans https://, le chemin ni le port.
Appuyez sur Ajouter.

Un domaine couvre aussi ses sous-domaines : example.com autorise shop.example.com. Appuyez sur pour retirer un site, puis confirmez ; une fois le dernier retiré, la clé fonctionne depuis n'importe quel site web. Vous recevez un e-mail chaque fois qu'un site web est retiré d'une clé.

La liste s'applique aux navigateurs. Une carte intégrée ne s'ouvre que sur une page d'un site de la liste ; si le navigateur n'indique pas sur quelle page elle se trouve, elle est refusée. Une requête à l'API REST envoyée depuis une page web doit venir d'un site de la liste. Une requête envoyée par votre propre serveur n'indique aucun site web et n'est pas vérifiée. Measure Map Online lui-même est toujours autorisé, pour que les aperçus de cette page continuent de fonctionner.

Les restrictions de site web avec deux domaines autorisés

Voir comment la clé est utilisée#

La section Utilisation additionne toutes vos clés de production : les chiffres continuent quand vous remplacez une clé. Elle affiche les requêtes des 30 derniers jours, des cartes intégrées comme de l'API REST, avec une barre par jour ; le total Depuis le début ; le Dernier accès ; la date de création de la clé actuelle (Clé créée) ; et les Principaux domaines : les sites web qui utilisent le plus vos clés. Un site web que vous ne reconnaissez pas dans cette liste est une raison de restreindre ou de remplacer la clé.

Les requêtes du bac à sable ne sont pas comptées : les chiffres n'apparaissent donc qu'en Production. Les requêtes que fait cette page elle-même, dans Essayer l’API et les aperçus, ne le sont pas non plus.

Protéger votre clé#

Ne donnez à chaque clé que l'accès dont elle a besoin. Une clé placée dans une page web (par exemple dans l'adresse d'une intégration) ne doit avoir que Cartes intégrées.
Cette clé peut modifier vos données. Gardez-la sur votre serveur, jamais dans une page web ou une application.
Limitez une clé utilisée dans des pages web à vos propres sites web.
Laissez la clé masquée sur la page quand vous partagez votre écran ; la copier ne nécessite pas de l'afficher.
Si une clé a pu fuiter, créez-en une nouvelle et révoquez immédiatement l'ancienne sous Clés précédentes.
Construisez et testez avec une clé Bac à sable, pour que vos essais ne se retrouvent jamais parmi vos vrais projets.