N-WaysClés d’API et sécurité
Chaque requête porte une clé d’API. Limitez chaque clé aux sites, applications ou serveurs qui l’utilisent et aux API dont elle a besoin : une clé copiée ne sert alors à personne d’autre.
Sur cette page
Obtenir des clés. Inscrivez-vous dans la console partenaire avec Google, Apple ou un e-mail : votre première clé est créée aussitôt, et vous créez vous-même les suivantes, avec leurs restrictions ; chaque clé ne s’affiche qu’une fois, à sa création. Sans clé, les API, les tuiles et les polices refusent les requêtes venant d’autres sites web que ceux de N-Ways (403).
Projets et clés
Un projet regroupe vos clés, les API qu’elles peuvent appeler, leurs quotas et leur consommation. Utilisez un projet par application et par environnement (par exemple Appli livreur et Appli livreur, test), pour qu’un script de test n’épuise jamais le quota de la production.
Un projet peut avoir plusieurs clés. Donnez à chaque site web, application et serveur sa propre clé : vous pourrez la restreindre au plus juste et la remplacer sans toucher aux autres.
Envoyer votre clé
Ajoutez key=VOTRE_CLE_API à l’adresse de chaque requête : appels aux services web, tuiles et polices. Le SDK Maps le fait pour vous.
GET /maps/v1/geocode?q=Wuse+2+Abuja&key=VOTRE_CLE_API HTTP/1.1
Host: nways.ngDepuis un serveur, vous pouvez plutôt l’envoyer dans un en-tête, pour qu’elle n’apparaisse pas dans vos journaux d’adresses :
GET /maps/v1/geocode?q=Wuse+2+Abuja HTTP/1.1
Host: nways.ng
X-NWays-Api-Key: VOTRE_CLE_APIDepuis une page web, les deux fonctionnent : avec l’en-tête, le navigateur demande d’abord l’autorisation (une requête CORS préalable), que N-Ways accorde ; la requête elle-même est ensuite vérifiée. Les réponses destinées à votre site portent Access-Control-Allow-Origin pour lui, afin que votre page puisse les lire, et les refus aussi, afin que votre code puisse en lire la raison.
N-Ways ne répond aux pages d’autres sites web que si elles envoient une clé que ce site a le droit d’utiliser. Sans clé, les données cartographiques et les API sont réservées aux applications N-Ways.
Restrictions d’application
Une restriction d’application indique où une clé peut être utilisée. Chaque clé a un seul type de restriction :
| Type | À utiliser pour | Comment N-Ways la vérifie |
|---|---|---|
| Sites web | Les cartes et les appels depuis une page web | L’adresse de la page envoyée par le navigateur (l’en-tête Referer ou Origin) |
| Applications Android | Les appels depuis votre application Android | Le nom de package de l’application et l’empreinte SHA-1 de son certificat de signature, dans les en-têtes X-Android-Package et X-Android-Cert (le SDK Android les envoie pour vous) |
| Applications iOS | Les appels depuis votre application iPhone | Le bundle ID de l’application, dans l’en-tête X-Ios-Bundle-Identifier (le SDK iOS l’envoie pour vous) |
| Adresses IP | Les appels depuis vos serveurs | L’adresse d’où vient la requête |
| Aucune | Uniquement pour faire des essais | Rien. Ne mettez jamais en production une clé sans restriction. |
Adresses de sites web
Indiquez chaque site sur lequel la clé peut être utilisée. Un * remplace n’importe quel sous-domaine au début, ou n’importe quoi à la fin du chemin :
| Entrée | Autorise | N’autorise pas |
|---|---|---|
https://example.com/* | Toutes les pages de example.com | www.example.com, http://example.com |
https://*.example.com/* | www.example.com, shop.example.com | example.com lui-même : ajoutez-le aussi |
https://example.com/track/* | Les pages sous /track/ | Tout le reste du site |
http://localhost:5173/* | Votre ordinateur, pendant le développement | À garder uniquement sur une clé de développement |
Les navigateurs n’envoient souvent que l’origine du site, et non l’adresse complète de la page. Si une entrée basée sur un chemin ne correspond pas, autorisez le site entier.
Applications Android et iOS
Une entrée Android est composée du nom de package et du SHA-1 du certificat, séparés par un point-virgule : com.example.rider;DA:39:A3:EE:…:07:09 (les deux-points sont facultatifs). Utilisez l’empreinte du certificat avec lequel la boutique signe votre application. Une entrée iOS est le bundle ID : com.example.rider.
Adresses IP
Indiquez les adresses publiques de vos serveurs, une par ligne : des adresses uniques (203.0.113.7, 2001:db8::7) ou des plages (198.51.100.0/24). Derrière une passerelle NAT ou un répartiteur de charge cloud, indiquez l’adresse sortante de la passerelle.
Restrictions d’API
Une restriction d’API indique ce qu’une clé peut appeler. Choisissez uniquement ce que l’application utilise :
| API | Couvre |
|---|---|
| Cartes (tuiles) | Les styles hébergés (/maps/v1/styles/…, un chargement de carte chacun), les tuiles et les polices (/maps/v1/tiles/…, /maps/v1/fonts/…, et les anciennes adresses /tiles/…, /fonts/…) : ce que lisent les SDK Maps |
| Cartes statiques | /maps/v1/staticmap |
| Géocodage | /maps/v1/geocode, /reverse, /postcodes/…, /ghanapost/…, /pluscodes/… (et les anciennes adresses /v1/geocode, /v1/reverse, /v1/postcodes/{code}, /v1/ghanapost/{code}) |
| Saisie semi-automatique | /maps/v1/autocomplete |
| Validation d’adresse | POST /maps/v1/addresses/validate |
| Lieux | /maps/v1/places/… (et les anciennes adresses /v1/search, /v1/places, /v1/places/{id}, POST /v1/places/along) |
| Itinéraires | POST /maps/v1/routes/compute (et les anciennes adresses POST /v1/routes, POST /v1/routes/check) |
| Matrice d’itinéraires | POST /maps/v1/routes/matrix |
| Optimisation de tournées | POST /maps/v1/routes/optimize |
| Tarifs de course | /maps/v1/fares/estimate (et l’ancienne adresse /v1/fares/estimate) |
| Trafic | /maps/v1/traffic (et l’ancienne adresse /v1/traffic) |
| Flotte | /maps/v1/fleet/… sauf le flux de trafic : véhicules, positions, livraisons, liens de suivi, webhooks, packs hors connexion |
| Flux de trafic | /maps/v1/fleet/traffic-feed |
| Photos | Les photos des lieux (/photos/…) |
Une clé ne permet jamais à personne de signaler, d’ajouter ou de modifier quoi que ce soit sur la carte, et n’accède jamais aux comptes. Seule l’API Flotte modifie des données, et uniquement les vôtres (vos véhicules, livraisons et webhooks).
Un appel à une API que la clé n’a pas le droit d’utiliser reçoit la réponse 403 avec la raison API_KEY_SERVICE_BLOCKED. Erreurs de clé
Renouveler une clé
Remplacez une clé quand elle a pu fuiter, quand une personne qui la connaissait s’en va, ou une fois par an :
- Demandez-nous de régénérer la clé, ou d’en créer une nouvelle avec les mêmes restrictions. Une clé régénérée peut garder son ancienne valeur active pendant 24 heures, le temps de publier la nouvelle.
- Mettez la nouvelle clé dans votre site, votre application ou votre serveur, et publiez la mise à jour.
- Regardez la consommation de l’ancienne clé baisser dans la console. Les applications sur téléphone se mettent à jour lentement : comptez des jours, pas des minutes.
- Désactivez l’ancienne clé. Les requêtes qui l’utilisent reçoivent
403 API_KEY_PAUSEDen quelques secondes, avec un message disant que la clé est en pause. Si quelque chose ne marche plus, réactivez-la le temps de corriger. - Supprimez l’ancienne clé quand sa consommation est restée à zéro.
Si une clé fuite
Restreignez-la tout de suite (une clé de site web à vos sites, une clé de serveur à vos adresses IP), puis renouvelez-la comme ci-dessus. Si vous ne pouvez pas la restreindre, désactivez-la : votre application ne fonctionnera plus avec elle tant que vous n’aurez pas publié la nouvelle clé. Prévenez-nous à hello@nways.ng et nous vous aiderons à vérifier sa consommation.
Bonnes pratiques
- Une clé par site web, application et serveur, chacune avec une restriction d’application et uniquement les API dont elle a besoin.
- Gardez les clés de serveur sur les serveurs. Ne mettez jamais une clé restreinte par adresse IP dans une page web ou une application, et ne commitez jamais une clé dans votre dépôt de code : lisez-la depuis une variable d’environnement ou votre coffre à secrets.
- Appelez les services web depuis votre serveur quand c’est possible. Une page web qui a besoin d’itinéraires peut les demander à votre serveur, qui appelle N-Ways avec une clé de serveur.
- Fixez vos propres plafonds sur chaque clé, pour qu’un bug ou un abus ne puisse pas épuiser votre quota. Quotas et limites
- Séparez test et production, dans des projets différents.
- Supprimez ce que vous n’utilisez pas : les clés inutilisées, et les API dont une clé n’a plus besoin.