Skip to content

Verify domain ownership

Before Vex Raptor can actively scan an external target in production (or in any environment where target authorization is enabled), you must prove that you control the domain. This prevents the platform from being used as an open relay against third-party sites.

This is separate from the written authorization checkbox on the Pentest form: that checkbox is your legal confirmation; domain verification is the technical proof that you can change DNS or publish content on the host.

When verification is required

Situation Verification
Production/staging, target is a public hostname (e.g. app.example.com) Required (unless your contract defines an operator bypass)
localhost, private IPs, lab ranges Not required (intentional lab use)
Self-hosted dev with REQUIRE_TARGET_AUTHORIZATION=false Off unless you opt in via env

If you skip verification, the API returns 403 with target_not_authorized and the console shows Prove domain ownership.

Before you start

  • Organization admin role (domain instructions and verify API require admin).
  • A target URL you are allowed to test, e.g. https://app.example.com.
  • Access to DNS or website files for that domain (or someone on your team who can publish a DNS TXT record, HTTP file, or HTML meta tag).

Step by step (console)

  1. Sign in to the console and open Pentest (/scan).

  2. Enter your target URL (include https:// unless your deployment accepts bare hostnames).

  3. Start the engagement (or continue until the scan is blocked). If the domain is not verified yet, the Prove domain ownership panel appears with your exact token and record names — always use the values from the console, not a generic example.

  1. Choose one verification method (tabs in the panel):

    Best if you manage DNS (Cloudflare, Route 53, GoDaddy, etc.).

    • Name / host: _vex-verify.<your-domain> (the panel shows the full name).
    • Type: TXT
    • Value: vex-verify=<32-character token> (copy from the panel).
    • Save the record and wait for DNS propagation (minutes to 48 hours).

    Best if you can upload a file to the site root (static hosting, your server).

    • Publish a plain-text file at: https://<your-domain>/.well-known/vex-verify.txt
    • Body = the token line shown in the console (same as the TXT value content).

    Best for site builders (Wix, Squarespace, WordPress) where you can edit <head>.

    • Add to the public homepage <head>: <meta name="vex-verify" content="<token>">
    • The token is the 32-character hex value from the panel (without the vex-verify= prefix used in DNS).

  2. Click I've published it — Verify now. The platform performs a live check.

  3. On success, launch the pentest again. The written authorization checkbox for the target is still required before LAUNCH PENTEST.

Step by step (API)

Useful for automation or support scripts. Requires admin JWT.

Get instructions (token and record names for your org and target):

curl -sS "https://<host>/api/v1/pentest/authorize/instructions?target=https%3A%2F%2Fapp.example.com" \
  -H "Authorization: Bearer <JWT>"

Verify after publishing:

curl -sS -X POST "https://<host>/api/v1/pentest/authorize/verify" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://app.example.com"}'

Response shape: { "verified": true|false, "method": "dns_txt"|"http_file"|"meta_tag"|null, "domain": "app.example.com" }.

OpenAPI details: /api/docs on your instance.

What you will see

  • Verified: scan proceeds past the domain gate (subject to quota, license, and SSRF rules).
  • Not verified yet: console message that DNS may take up to 24–48 hours, or that HTTP/meta proof must be on the public homepage without login.

Common problems

Symptom What to check
403 target_not_authorized Complete verification; token is per organization — another org’s proof does not apply.
Verify fails immediately after DNS edit TTL/propagation; try dig TXT _vex-verify.example.com from an external resolver.
HTTP file fails File must be reachable over HTTPS (or HTTP if that is what you scan), no auth wall, exact path .well-known/vex-verify.txt.
Meta tag fails Tag must appear in the first part of the homepage HTML; some builders inject scripts before meta — use DNS or HTTP file instead.
Wrong subdomain Proof is for the registrable host of the target URL; www vs apex must match what you scan.

Security and privacy

  • Tokens are derived per organization and domain; do not share them in public tickets.
  • Only scan domains you own or have written permission to test. See Responsible use.

Next steps