Overview

The external developer API is intentionally separate from the paid-user account API. It gives approved developers API-key protected access to domain authenticity verdicts and security score advisory statements.

External developer keys do not work on the paid-user /api/v1 account API and do not return tracked-domain history, signed-in reports, scan ownership IDs or paid evidence packs.

Authentication

Developer API keys are available on Pro and MSP plans. If you already have an eligible MyDomainRisk account, create a Developer API - authenticity and score advisory key from the account area and send it as a Bearer token.

Authorization: Bearer mdr_live_<id>_<secret>

Use developer keys only from server-side code. Do not put them in browser JavaScript, mobile apps, public repositories or client-side logs.

Validate a key before building against it:

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

{
  "account": "developer@example.com",
  "api": "developer",
  "scope": "developer_peek",
  "available_endpoints": [
    "/api/developer/v1/peek/security",
    "/api/developer/v1/peek/authenticity"
  ]
}

If you need API access and do not have an account, or want to discuss a partner arrangement, contact support@mydomainrisk.com.

Security score advisory

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

Example response:

{
  "domain": "example.com",
  "score": 82,
  "grade": "B",
  "score_summary": {
    "label": "Good",
    "message": "No urgent security issues found, but there are improvements to consider."
  },
  "findings": [
    {
      "title": "DMARC policy could be stronger",
      "severity": "medium",
      "summary": "The domain publishes email protection records, but the policy is not yet at its strongest setting."
    }
  ],
  "total_findings": 1,
  "cache_hit": false,
  "cache_meta": { "kind": "security", "max_age_seconds": 1200 },
  "scan_time_ms": 842
}

Authenticity verdict

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

You can include optional brand context when the expected organisation name is known:

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

Example response:

{
  "domain": "example.com",
  "verdict": "genuine",
  "findings": [],
  "total_findings": 0,
  "factual": {
    "resolves": true,
    "registrar": "Example Registrar Ltd",
    "domain_age_days": 10950,
    "tls_valid": true
  },
  "cache_hit": false,
  "cache_meta": { "kind": "authenticity", "max_age_seconds": 1200 },
  "scan_time_ms": 936
}

Authenticity verdict values:

genuine	No material authenticity concern visible. Map to pass / green.
probablyLegit	Likely legitimate with minor caveats. Map to pass / green.
uncertain	Cannot confidently classify. A human should review. Map to review / amber.
suspicious	Concerning signals present. Treat with caution. Map to review or fail / amber-red.
malicious	Strong malicious or impersonation signals. Do not treat as safe. Map to fail / red.

For simple traffic-light integrations, map genuine and probablyLegit to pass, uncertain and suspicious to review, and malicious to fail.

Fields

Security score advisory fields

domain	The normalised domain submitted for checking.
score	Security score advisory on a 0–100 scale. Higher is better. May be null.
grade	Display grade derived from the score. Treat as presentation text. May be null.
score_summary	Plain-English score summary object or string. Display rather than deriving your own explanation.
findings	Array of current public findings. Each item has display text such as title, severity, and summary when available.
total_findings	Count of current public findings.
cache_hit	Whether the response was served from the short-lived result cache.
cache_meta	Cache metadata including response type and current cache age guidance.
scan_time_ms	Runtime for the request in milliseconds.

Authenticity verdict fields

domain	The normalised domain or URL host submitted for checking.
verdict	One of: genuine, probablyLegit, uncertain, suspicious, malicious.
findings	Array of current public findings. Each item has display text such as title, severity, and summary when available.
total_findings	Count of current public findings.
factual	Public factual context such as resolution, domain age, TLS, and registration detail when available. Fields may be absent when data is unavailable.
cache_hit	Whether the response was served from the short-lived result cache.
cache_meta	Cache metadata including response type and current cache age guidance.
scan_time_ms	Runtime for the request in milliseconds.

Results are cached for up to 20 minutes. There is no force-refresh option on the developer API; present results as a recent advisory rather than a permanent decision for domains that may have just changed.

Limits and errors

Developer API requests are limited to 60 requests per minute per key and per IP. Platform spend guards apply in the same way as the public domain-check tier.

400/422	Invalid request body, query string or malformed domain.
401	Missing, malformed, unknown or revoked API key.
403	Wrong key type, or account not eligible for API access.
429	Rate limit or platform guard reached.
503	Temporary queue, cache or quota-store issue. Retry later.

Acceptable use

The API is for legitimate business, security, fraud-prevention, customer-protection and compliance workflows. MyDomainRisk performs non-intrusive external analysis only.

Allowed

Onboarding and signup checks.
Customer, partner and domain review.
Internal fraud, risk and security workflows.

Not allowed

Exploitation, attack simulation or credential testing.
Bypassing quotas, cooldowns or access controls.
Using paid-user account keys as external developer keys.

Privacy and data handling

The developer API receives the domain and request metadata needed to provide the service, authenticate the caller, enforce limits and protect the platform. MyDomainRisk does not sell API submission data.

Developer API results may be cached and counted in aggregate telemetry according to the same public domain-check operating model and the MyDomainRisk privacy policy. For privacy questions, contact support@mydomainrisk.com.

Changelog

2026-06-25

Public developer docs updated with key validation, example JSON responses, verdict values, rate limits, and cache guidance for the separate external developer API.

Developer API docs for authenticity verdicts and score advisory