EN
Aller au contenu

Authentification

Chaque requête à la passerelle (cartes, géocodage, itinéraires) nécessite une clé API unmap. Il n'y a pas de palier non authentifié : même le forfait gratuit fonctionne par clé; il ne facture simplement pas le trafic d'origine dev (voir Forfaits et limites).

Formes de clé

Une clé ressemble à um_live_... ou um_test_.... Le préfixe est vérifié avant toute autre chose : une chaîne qui ne commence pas par l'un des deux est rejetée sans consultation du stockage des clés.

  • um_live_ est votre clé de production.
  • um_test_ est pour le développement local et la préproduction. Le guide de démarrage de @unmap/sdk fournit une clé de démonstration publique um_test_, limitée en débit et sûre pour essayer l'API avant d'avoir la vôtre.

Les deux formes sont traitées de la même manière par la passerelle : authentifiées, limitées en débit et, hors trafic d'origine dev, comptabilisées dans votre forfait. Le préfixe indique l'environnement de la clé; il n'exempte pas à lui seul une requête de la facturation. Le fait qu'une requête compte comme trafic « dev » gratuit dépend de son Origin. Voir Forfaits et limites pour la règle exacte.

Présenter la clé

Trois formes sont acceptées :

  • Authorization: Bearer <key> est la forme normale côté serveur.
  • X-API-Key: <key> est pour les clients qui réservent l'en-tête Authorization.
  • ?key=<key> est un paramètre de requête. Obligatoire pour les tuiles, glyphes et sprites, puisque MapLibre GL ne peut pas joindre d'en-têtes personnalisés à ces requêtes. Les clients @unmap/* utilisent cette forme pour chaque requête, tuiles comme JSON, donc avec le SDK vous ne présentez jamais la clé vous-même; les formes par en-tête servent à appeler la passerelle directement.
# En-tête Authorization
curl "https://api.unmap.dev/geocode/search?q=Calgary+Tower" \
  -H "Authorization: Bearer $UNMAP_API_KEY"
 
# En-tête X-API-Key
curl "https://api.unmap.dev/geocode/search?q=Calgary+Tower" \
  -H "X-API-Key: $UNMAP_API_KEY"
 
# Paramètre de requête, la forme que MapLibre utilise pour les tuiles, glyphes et sprites
curl "https://api.unmap.dev/tiles/11/375/685.mvt?key=$UNMAP_API_KEY" -o tile.mvt

Si plusieurs formes sont présentes, l'en-tête gagne : Authorization, puis X-API-Key, puis ?key=.

La passerelle retire ?key= avant de transmettre une requête à un service en amont ou de ranger une réponse dans le cache périphérique, donc une tuile ou une réponse de géocodage en cache est partagée entre les clients et ne porte jamais la clé de qui que ce soit. Ce qu'elle conserve, c'est un hachage de la clé, compté par point de terminaison pour la facturation.

La clé peut-elle aller dans le navigateur?

Oui, et c'est nécessaire. C'est le navigateur qui récupère les tuiles, donc la clé voyage dans des URL que n'importe qui peut lire dans le panneau réseau. Une clé cartographique est un identifiant public au même sens qu'une clé publiable Stripe : la trouver n'est pas un exploit, et il n'existe pas de variante réservée au serveur qui permettrait d'afficher une carte sans elle.

Le secret n'est donc pas le contrôle. Deux autres choses le sont, toutes deux dans le tableau de bord :

  • Des origines autorisées, définies par clé. Inscrivez sur la clé elle-même les origines exactes d'où elle peut être présentée, une par ligne. Une clé dotée d'une liste est stricte : les requêtes provenant d'ailleurs sont refusées par un 403 portant le code origin_not_allowed, tout comme celles sans en-tête Origin ni Referer. Une clé dont la liste est vide n'a aucune restriction, ce qui est le cas attendu d'une clé de serveur. Les origines dev ne sont pas implicites : inscrivez http://localhost:3000 si c'est là que vous développez.
  • Le plafond de dépenses, fixé à 0 $ au départ sur chaque forfait payant. Quelqu'un qui utiliserait une clé trouvée ne peut pas générer un dépassement auquel vous n'avez pas consenti. Il pourrait tout de même consommer vos appels inclus, et c'est à cela que sert la liste d'origines.

Utilisez deux clés plutôt qu'une : une clé cadrée pour le navigateur et une clé sans restriction pour votre serveur. Un serveur n'envoie aucun Origin, donc cadrer la clé qu'il utilise reviendrait à refuser votre propre serveur.

Soyez lucide sur ce que cela apporte. Origin et Referer sont posés par le navigateur, et tout ce qui n'en est pas un peut envoyer ce qu'il veut. Une liste d'origines empêche une clé récupérée sur votre page de fonctionner sur la page de quelqu'un d'autre. Elle n'arrête pas un script. Si vous croyez qu'une clé a été dérobée, révoquez-la depuis le tableau de bord et créez-en une autre. Les règles complètes sont dans Forfaits et limites.

Obtenir une clé

Connectez-vous à unmap.dev/fr/signin avec un lien magique par courriel ou GitHub, puis créez une clé dans le tableau de bord. Ce flux de connexion est une session navigateur (un témoin, pas une clé API) : il sert à gérer votre compte, pas à authentifier votre application. Votre application utilise toujours la clé elle-même, présentée de l'une des trois façons ci-dessus.

Mauvaises clés

Une clé manquante ou inconnue retourne 401 :

// aucune clé présentée
{ "error": "missing API key", "code": "unauthorized" }
 
// la clé n'existe pas, ou a été révoquée
{ "error": "invalid or disabled API key", "code": "unauthorized" }

Les clés sont recherchées par hachage de la valeur présentée, et non stockées en clair.

Dépasser la limite de débit de 1 000 requêtes par 60 secondes par clé et par emplacement Cloudflare retourne 429 avec un en-tête Retry-After :

{ "error": "rate limit exceeded", "code": "rate_limited" }

Voir Erreurs pour le contrat complet, y compris les codes d'application de forfait (quota_exceeded, spend_cap, billing_required, origin_not_allowed) qu'une requête peut rencontrer une fois authentifiée.