TMaps - API Cartographie Tunisie

Authentification

Comment passer votre clé API, comment fonctionnent les domaines autorisés (Origin/Referer) et comment appeler l'API depuis un serveur.

Toute requête vers l’API TMaps doit être authentifiée à l’aide d’une clé API (api_key), créée depuis la console TMaps.

Format de la clé

Une clé API TMaps a la forme suivante :

ak_a1b2c3d4e5f607xxxXXXxXXxxXX

Le préfixe ak_ est suivi de 32 caractères hexadécimaux. Considérez votre clé comme un mot de passe : ne la versionnez pas dans un dépôt public et ne l’exposez pas dans des logs côté client si possible.

Passer la clé : api_key en query string

Tous les endpoints (GET comme POST) acceptent la clé via le paramètre api_key dans la query string.

GET https://api.tmaps.tn/{endpoint}?api_key=YOUR_API_KEY&... 
curl "https://api.tmaps.tn/geocoding/forward?q=Tunis&api_key=YOUR_API_KEY"

Pas de header Authorization

TMaps n’utilise pas de header Authorization: Bearer …. La clé passe toujours par le paramètre api_key de la query string, y compris pour les requêtes POST.

Domaines autorisés (Origin / Referer)

Pour empêcher qu’une clé exposée dans le code JavaScript d’un site soit réutilisée ailleurs, vous pouvez restreindre une clé à une liste blanche de domaines depuis la console (rubrique Authorized Domains).

À chaque requête, le backend vérifie en cascade :

  1. Le header Origin envoyé par le navigateur ;
  2. À défaut, le header Referer.

Si l’un des deux est présent et ne correspond à aucun domaine autorisé pour la clé, la requête est rejetée avec un statut 403 :

403 Domaine non autorisé pour la clé 
{
"error": "domain not authorized"
}

Règles précises

  • Pas de wildcard. *.monsite.tn n’est pas accepté : ajoutez chaque sous-domaine explicitement (app.monsite.tn, admin.monsite.tn, …).
  • localhost doit être ajouté. Pour le développement local, ajoutez localhost (et 127.0.0.1 si vous l’utilisez) à votre liste de domaines.
  • Plusieurs domaines par clé : une même clé peut être autorisée sur plusieurs domaines.
  • Plusieurs clés sur un domaine : un même domaine peut être autorisé pour plusieurs clés (par ex. une clé pour la prod, une autre pour la pré-prod).
  • HTTPS uniquement : les requêtes en HTTP sont systématiquement rejetées en 403.

Appels côté serveur

Quand votre code tourne dans un environnement server-side (Node, PHP, Python, Go, mobile natif…), les headers Origin et Referer sont absents de la requête. Dans ce cas, la liste des domaines autorisés est ignorée et la clé fonctionne sans restriction.

Conseil de sécurité

Pour une intégration purement backend, créez une clé dédiée sans aucun domaine autorisé : elle restera utilisable depuis vos serveurs (pas d’Origin) mais sera bloquée côté navigateur si elle fuite dans un repo public.

Erreurs d’authentification

StatutCauseBody
401api_key absent, désactivé ou révoqué{"error":"missing api_key"}
403Origin/Referer non autorisé, ou requête HTTP{"error":"domain not authorized"}

Voir la liste complète sur la page Codes d’erreur.

Bonnes pratiques

  • Une clé par environnement (dev / staging / prod) et par usage (frontend / backend).
  • Restreindre les clés exposées au navigateur à la liste exacte de vos domaines.
  • Désactiver immédiatement une clé suspecte depuis la console (la clé peut ensuite être réactivée plus tard ou révoquée définitivement).
  • Surveiller l’usage depuis l’onglet Usage de la console pour détecter un pic anormal.