EN
Aller au contenu

Authentification

Les appels aux API de données protégées, dont les cartes, le géocodage, les itinéraires et Optimize, exigent une clé API Unmap sur tous les forfaits. La plupart du trafic d'origine dev est gratuit; Optimize facture par envoi effectué même depuis une origine dev. Voir les 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 suivent les mêmes règles d'authentification, de débit et de facturation. Le préfixe indique l'environnement de la clé et n'exempte pas une requête de la facturation. Pour la plupart des points de terminaison, Origin ou Referer détermine si le trafic dev est gratuit. Optimize applique ses règles par envoi sur toutes les origines. Voir les forfaits et limites.

Présenter la clé

Quatre 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.
  • X-Goog-Api-Key: <key> accepte une clé Unmap pour les clients qui utilisent l'en-tête de clé API de Google. Il fonctionne sur tous les points de terminaison de données protégés. Google Route Optimization utilise OAuth; consultez le guide de migration pour remplacer ses identifiants.
  • ?key=<key> est un paramètre de requête. Les URL générées dans les styles utilisent cette forme pour les tuiles, le relief, les courbes de niveau, les glyphes et les sprites. Ces points de terminaison acceptent aussi les trois en-têtes ci-dessus pour les appels directs. Les clients SDK joignent la clé automatiquement; optimizeTours() utilise X-API-Key.
# 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"
 
# En-tête X-Goog-Api-Key, comme l'envoie un client REST de Google
curl "https://api.unmap.dev/geocode/search?q=Calgary+Tower" \
  -H "X-Goog-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, les en-têtes gagnent, dans cet ordre : Authorization, puis X-API-Key, puis X-Goog-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, renouvelez-la depuis le tableau de bord : vous obtenez une nouvelle clé avec le même nom, les mêmes origines et les mêmes compléments, et l'ancienne cesse de fonctionner. 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. Le tableau de bord peut afficher ou copier une clé de nouveau en tout temps. 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 quatre 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é supprimé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.