Authentification

L'API TrustyData s'authentifie par clé Bearer dans le header Authorization. Une clé identifie un client unique et porte les autorisations associées à son plan.

Format du header

Authorization: Bearer <votre_cle_api>

Pas d'autre mécanisme d'authentification — pas de cookies, pas d'OAuth, pas de signature de requête. Le seul endpoint qui n'exige aucune clé est GET /version.

Récupérer une clé

Les clés sont créées et révoquées dans votre espace client (trustydata.fr, section Clés d'API). À la création, le cleartext est affiché une seule fois — copiez-le immédiatement vers votre gestionnaire de secrets. Si vous le perdez, créez-en une nouvelle et révoquez l'ancienne.

Règle cardinale : une clé = un client

Pour les agences qui revendent l'API à leurs propres clients, un mode dédié existe : chaque sous-client a sa propre clé, son propre quota, et apparaît distinctement dans votre tableau de bord d'agence. Contactez-nous pour activer ce mode.

Sécurité côté client

La clé doit rester côté serveur. Ne l'exposez jamais :

• dans une page HTML ou un bundle JavaScript public
• dans une application mobile distribuée (elle est trivialement extractible)
• dans un dépôt Git public — utilisez des variables d'environnement
• dans des logs d'accès ou des outils d'observabilité tiers

Le pattern recommandé pour une démo publique : votre serveur (Flask, Express, FastAPI…) reçoit la requête utilisateur, ajoute le header Authorization avec la clé stockée en variable d'environnement, appelle l'API TrustyData, puis renvoie la réponse au navigateur. Le navigateur ne voit jamais la clé.

# Flask — proxy côté serveur
import os, requests
from flask import Flask, request, jsonify

app = Flask(__name__)
API_KEY = os.environ["TRUSTYDATA_API_KEY"]

@app.get("/api/address/autocomplete")
def proxy_autocomplete():
    r = requests.get(
        "https://api.trustydata.app/services/v1/address/autocomplete",
        params={"q": request.args.get("q", "")},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=5,
    )
    return jsonify(r.json()), r.status_code

Rotation des clés

Aucune contrainte de rotation imposée, mais il est sain de renouveler une clé périodiquement, et obligatoire en cas de fuite suspectée :

1. Créez une nouvelle clé dans l'espace client
2. Déployez vos services avec la nouvelle clé
3. Vérifiez que l'ancienne n'est plus utilisée (graphes d'usage)
4. Révoquez l'ancienne clé

Les deux clés peuvent coexister pendant la transition — il n'y a pas de limite à 1 seule clé active par compte.

Erreurs d'authentification

Code	Signification	Action
401	Clé manquante, invalide, ou révoquée	Vérifiez le header Authorization et la clé
403	Clé valide mais plan insuffisant pour cet endpoint	Upgrader le plan ou utiliser un autre endpoint — voir Plans
429	Quota mensuel dépassé	Attendre la prochaine période ou upgrader
503	Service d'authentification temporairement indisponible	Retry avec backoff exponentiel (5s, 15s, 45s…)

Endpoint /version — sans clé

GET /version est volontairement public — il permet de vérifier que l'API est joignable depuis votre infrastructure sans consommer le quota :

curl https://api.trustydata.app/services/v1/version

Prochains pas

• Plans & quotas — ce que chaque plan ouvre
• Codes d'erreur — gestion complète des erreurs
• Référence complète — tous les endpoints