Documentation de l'API développeur pour les verdicts d'authenticité et les indications de score

L'API développeur externe est volontairement distincte de l'API compte des utilisateurs payants. Elle donne aux développeurs approuvés un accès, protégé par clé API, aux verdicts d'authenticité de domaine et aux indications de score de sécurité.

Les clés développeur externes ne fonctionnent pas sur l'API compte des utilisateurs payants /api/v1 et ne renvoient ni l'historique des domaines suivis, ni les rapports de l'espace connecté, ni les identifiants de propriété des analyses, ni les dossiers de preuves payants.

MyDomainRisk effectue des vérifications à deux niveaux de profondeur, et cette API vous donne le moins approfondi. La différence n'est pas une limite sur le nombre de vérifications que vous pouvez lancer : elle porte sur le volume d'analyse effectué et le niveau de détail renvoyé.

Ce que la vérification rapide ne fait pas

• Elle n'explique pas un constat. Vous obtenez un intitulé et une gravité, pas l'analyse qui le sous-tend, les étapes de correction ni les sources qui y ont contribué.
• Son score peut être plus élevé que celui d'une analyse complète, jamais plus bas. Elle lit un index d'exposition plus léger, si bien que quatre vérifications plus approfondies ne peuvent pas le faire baisser. Dans ce cas, coverage_note le signale dans la réponse : ne présentez pas le chiffre sans cette mention. Lorsque les éléments essentiels ne peuvent pas être collectés, il n'y a aucun score (score vaut null, jamais zéro) et score_note en indique la raison.
• Elle peut renvoyer un verdict provisoire d'authenticité. Lorsque enrichment_status est pending, deux signaux plus lents sont encore en cours et le verdict peut encore changer. Rien ne vous est envoyé lorsqu'ils se terminent. Redemandez le même domaine un peu plus tard et vous recevrez la réponse enrichie, qui indique completed. Un verdict not_applicable n'a nécessité aucun signal lent et ne changera pas, quel que soit le nombre de demandes. C'est exactement le comportement du site web : un visiteur n'est pas averti non plus.
• Elle n'a peut-être pas lu la page d'accueil. homepage.reviewed indique si elle l'a lue, et homepage.blocked_by nomme ce qui l'en a empêchée. « Rien trouvé » et « la page n'a pas pu être récupérée » sont des réponses différentes et ne doivent pas être affichées de la même manière.
• Les résultats sont mis en cache jusqu'à 20 minutes et il n'est pas possible de forcer l'actualisation. Un domaine modifié au cours des dernières minutes peut ne pas encore le refléter.

Comme il s'agit de la même vérification que celle qu'un visiteur peut lancer, elle bénéficie du même quota : cinq par heure. Elle ne consomme pas le quota de vérifications quotidiennes du compte, qui est réservé aux analyses complètes.

Ce sont des réponses au niveau du résultat, pour l'évaluation et le tri. Elles ne remplacent pas une analyse complète d'un domaine dont vous êtes responsable.

Le contrat complet de l'API est publié au format OpenAPI 3.1 : validez les réponses dans votre CI ou générez-en des clients typés plutôt que de recopier les tableaux ci-dessous.

curl -sS https://mydomainrisk.com/openapi.json

Le même document est accessible depuis l'hôte de l'API, qui redirige vers l'adresse ci-dessus :

curl -sSL https://api.mydomainrisk.com/api/developer/v1/openapi.json

Il indique les valeurs exactes autorisées pour chaque champ dont les réponses sont en nombre fixe (verdicts, notes, catégories de score et gravités des constats), de sorte que rien sur cette page n'a à être déduit des exemples de réponses.

Il y en a deux, et elles répondent à des questions différentes. Avec l'API peek pour développeurs vous posez une question sur un domaine que vous nommez (son niveau de protection, ou s'il est bien ce qu'il prétend être) et obtenez le même résultat qu'un visiteur sur le site web. Avec l'API compte vous lisez votre propre compte : les domaines que vous suivez, leur historique d'analyses et leurs rapports, pour les automatisations que vous gérez vous-même.

Les deux sont disponibles sur toutes les offres, Gratuit compris. Ce qui change, ce n'est pas la porte mais la pièce : chaque clé est bornée par les limites de l'offre qui la porte, et GET /me renvoie ces limites pour que vous puissiez les lire plutôt que de les deviner.

Une clé a l'un des deux rôles et ne peut pas servir pour l'autre. Une clé développeur envoyée à un endpoint de l'API compte est refusée, et l'inverse l'est aussi.

Les clés de l'API développeur sont disponibles sur toutes les offres, Gratuit compris. Une clé est rattachée au compte de son propriétaire et peut faire ce que ce compte peut faire, rien de plus. Créez une clé de type Developer API - authenticity and score advisory depuis l'espace compte et envoyez-la comme jeton Bearer.

Authorization: Bearer mdr_live_<id>_<secret>

N'utilisez les clés développeur que dans du code côté serveur. Ne les placez pas dans du JavaScript de navigateur, des applications mobiles, des dépôts publics ni des journaux côté client.

Validez une clé avant de développer avec elle :

GET https://api.mydomainrisk.com/api/developer/v1/me
Authorization: Bearer mdr_live_<id>_<secret>

{
  "api": "developer",
  "version": "v1",
  "scope": "developer_peek",
  "tier": "pro",
  "capabilities": [
    { "operation_id": "getDeveloperCapabilities", "method": "GET", "path": "/me" },
    { "operation_id": "checkDomainSecurity", "method": "GET", "path": "/peek/security" },
    { "operation_id": "checkDomainAuthenticity", "method": "GET", "path": "/peek/authenticity" }
  ],
  "limits": {
    "requests_per_minute_per_key": 120,
    "requests_per_minute_per_ip": 60,
    "requests_per_hour_per_subnet": 150,
    "cache_max_age_seconds": 1200
  },
  "entitlements": {
    "security_score_advisory": true,
    "authenticity_verdict": true,
    "account_data": false,
    "force_refresh": false,
    "consumes_account_daily_allowance": false
  }
}

La réponse sur les capacités ne contient volontairement ni l'e-mail du compte ni aucune donnée client.

Si vous avez besoin d'un accès à l'API et n'avez pas de compte, ou si vous souhaitez discuter d'un partenariat, contactez support@mydomainrisk.com.

GET https://api.mydomainrisk.com/api/developer/v1/peek/security?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

Exemple de réponse :

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "score": 82,
  "grade": "B",
  "score_summary": {
    "bucket": "goodWithGaps",
    "label": "GOOD — GAPS REMAIN"
  },
  "score_basis": "point",
  "score_note": null,
  "findings": [
    {
      "title": "DMARC policy could be stronger",
      "severity": "medium"
    }
  ],
  "total_findings": 1,
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 842
}

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com
Authorization: Bearer mdr_live_<id>_<secret>

Vous pouvez ajouter un contexte de marque facultatif lorsque le nom de l'organisation attendue est connu :

GET https://api.mydomainrisk.com/api/developer/v1/peek/authenticity?domain=example.com&expected_brand=Example%20Ltd
Authorization: Bearer mdr_live_<id>_<secret>

Exemple de réponse :

{
  "domain": "example.com",
  "checked_at": "2026-08-17T12:00:00Z",
  "verdict": "genuine",
  "findings": [],
  "total_findings": 0,
  "factual": {
    "resolves": true,
    "registrar": "Example Registrar Ltd",
    "age_days": 10950,
    "has_tls": true
  },
  "cache": { "hit": false, "max_age_seconds": 1200 },
  "scan_time_ms": 936
}

Authenticité verdict : valeurs possibles

Pour une intégration simple de type feu tricolore, associez genuine et probablyLegit à « réussite », uncertain et suspicious à « à revoir », et malicious à « échec ».

Champs de l'indication de score de sécurité

Basez votre logique sur score_summary.bucket plutôt que de comparer score à vos propres seuils. Le bucket fait partie du contrat ; un seuil que vous choisissez vous-même n'en fait pas partie et s'écartera des nôtres sans qu'aucune erreur ne vous en avertisse.

Champs du verdict d'authenticité

Les résultats sont mis en cache jusqu'à 20 minutes. L'API développeur n'offre aucune option pour forcer l'actualisation ; présentez les résultats comme une indication récente plutôt que comme une décision définitive pour les domaines qui viennent peut-être de changer.

Les requêtes de l'API développeur sont limitées à 120 requêtes par minute et par clé, 60 par minute et par IP et 150 par heure et par sous-réseau.

Le quota qui limite réellement une vérification est de cinq par heure et par IP : le même quota que celui d'un visiteur qui lance la même vérification sur notre site web. Les limites par minute ci-dessus sont des garde-fous contre les rafales, qui s'y ajoutent. /me l'indique sous le nom peeks_per_hour_per_ip, et la lecture de /me n'est pas décomptée.

Ces vérifications ne consomment pas le quota de vérifications quotidiennes du compte. Ce quota est réservé aux analyses complètes, qui sont plus approfondies et sont tout autre chose.

Chaque échec renvoie la même structure JSON, sur chaque chemin et pour chaque statut. Basez votre logique sur error.code, pas sur le texte du message :

{ "error": { "code": "rate_limited", "message": "...", "retry_after_seconds": 30 } }

Considérez cette liste comme les codes qui méritent un traitement individuel, pas comme un ensemble fermé : reconnaissez ces codes et rabattez-vous sur le statut HTTP pour tout le reste, afin qu'un nouveau code ne casse jamais votre intégration.

Une réponse 429 comporte un en-tête Retry-After en plus du champ ci-dessus. Attendez en fonction de cette valeur plutôt que d'un intervalle fixe.

L'API est destinée à des usages légitimes : activité professionnelle, sécurité, prévention de la fraude, protection des clients et conformité. MyDomainRisk réalise uniquement une analyse externe non intrusive.

L'API développeur reçoit le domaine et les métadonnées de requête nécessaires pour fournir le service, authentifier l'appelant, appliquer les limites et protéger la plateforme. MyDomainRisk ne vend pas les données soumises via l'API.

Les résultats de l'API développeur peuvent être mis en cache et comptabilisés dans des statistiques agrégées, selon le même modèle de fonctionnement que les vérifications publiques de domaine et la politique de confidentialité de MyDomainRisk. Pour toute question de confidentialité, contactez support@mydomainrisk.com.