Domain verification (Verified host)

Notifly can scan ports of an arbitrary host. To prevent this from being used to attack someone else’s infrastructure, public hosts must first have their ownership verified — prove that the host is actually yours. A Verified host is a record “user X owns host Y” with a validity period of 365 days.

After verification, scanning that host runs in a faster mode (larger port batches and higher concurrency); unverified hosts can still be scanned, but more cautiously and slowly.

Two verification methods

Ownership can be verified with one of two methods (method):

method	What to place	Where Notifly checks
dns	DNS TXT record _notifly-verify.<host> with value = token	resolves TXT via the system DNS resolver
http	file /.well-known/notifly-verify.txt, single line = token	GET https://<host>/.well-known/notifly-verify.txt, fallback to http:// on failure

The token is a random UUID that Notifly issues at the start step. During checking the TXT record value (or the file content) is compared to the token after trimming whitespace (strings.TrimSpace), so extra spaces and a trailing newline won’t prevent verification.

HTTP check: HTTPS preferred

Notifly first requests the file over https://, and only if HTTPS is unavailable — over http://. Certificates are validated properly (self-signed will not work). Redirects are not followed: the file must be served directly with status 200. Request timeout is 5 seconds, and no more than 1 KB of the response is read.

Private hosts — auto-verification

If a host resolves only to private addresses, ownership does not need to be confirmed — such a record is created automatically with method auto-private.

Private addresses include (checked by the IsPrivateHost function):

• localhost;
• loopback 127.0.0.0/8 and ::1/128;
• RFC 1918 — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16;
• link-local 169.254.0.0/16 and fe80::/10;
• RFC 4193 ULA fc00::/7.

Protection against DNS rebinding

A host is considered private only if ALL of its addresses are private. If the hostname resolves to even one public address, auto-verification will not apply — verification via DNS or HTTP will be required.

For loopback addresses and localhost verification via DNS/HTTP is not possible in principle, so they are always considered verified.

Verification statuses

POST /verified-host/start returns a different status depending on the host:

status	When	HTTP code
already_verified	there is already a valid (non-expired) record for this host — returned in the host field	200
verified	host is private, record created automatically (method: "auto-private")	201
pending	public host — token and instruction issued, waiting for your step and check	200

A pending record is not saved anywhere until a successful check: you must remember the token on the client and send it back in /verified-host/check.

How to verify a domain

Step 1 — start verification

curl -X POST "$NOTIFLY_URL/verified-host/start" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{ "host": "example.com", "method": "dns" }'

Response for a public host:

{
  "status": "pending",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "method": "dns",
  "host": "example.com",
  "instruction": "Create a DNS TXT record: _notifly-verify.example.com with value: 550e8400-e29b-41d4-a716-446655440000"
}

Step 2 — place the proof

Method dns — create a TXT record in the domain zone:

_notifly-verify.example.com.  IN  TXT  "550e8400-e29b-41d4-a716-446655440000"

Method http — put a file at /.well-known/notifly-verify.txt so it is served at:

https://example.com/.well-known/notifly-verify.txt

The file content should be exactly the token, a single line:

550e8400-e29b-41d4-a716-446655440000

Step 3 — run the check

Provide host, method and token to check. Wait for DNS propagation (TTL may be a few minutes) before calling:

curl -X POST "$NOTIFLY_URL/verified-host/check" \
     -H "Content-Type: application/json" \
     -H "X-Notifly-Key: <client-token>" \
     -d '{
       "host": "example.com",
       "method": "dns",
       "token": "550e8400-e29b-41d4-a716-446655440000"
     }'

On success — the record is created, returns code 201 and the object itself:

{
  "id": 42,
  "host": "example.com",
  "method": "dns",
  "verifiedAt": "2026-06-23T10:00:00Z",
  "expiresAt": "2027-06-23T10:00:00Z"
}

If the token is not found (TXT not propagated, file unavailable, value mismatch) — a 422 code will be returned with an explanation in the error field, for example token not found in TXT records for _notifly-verify.example.com or HTTP 404 from https://example.com/.well-known/notifly-verify.txt. Simply retry check after fixing the issue.

HTTP check is often faster

The http method does not require waiting for DNS propagation — as soon as the file is available, check will succeed immediately. Convenient for hosts where you have access to the web server but not DNS zone editing rights.

Viewing and deletion

List of the user’s active (non-expired) verifications:

curl "$NOTIFLY_URL/verified-host" \
     -H "X-Notifly-Key: <client-token>"

[
  {
    "id": 42,
    "host": "example.com",
    "method": "dns",
    "verifiedAt": "2026-06-23T10:00:00Z",
    "expiresAt": "2027-06-23T10:00:00Z"
  }
]

Delete a verification (for example, if the host is no longer yours):

curl -X DELETE "$NOTIFLY_URL/verified-host/42" \
     -H "X-Notifly-Key: <client-token>"
# → {"ok":true}

You can only delete your record: someone else’s or a non-existent id will return 404.

REST API

All endpoints require a client (or MCP) token. Base URL — $NOTIFLY_URL (https://notifly.ru), auth header — X-Notifly-Key.

Method	Path	Description
GET	/verified-host	List of the user’s active verifications
POST	/verified-host/start	Start verification: { "host", "method" }, where method = dns or http. Returns status (already_verified / verified / pending) and for a public host — token + instruction
POST	/verified-host/check	Verify the placed proof: { "host", "method", "token" }. Success → 201 and the record object; failure → 422 with error
DELETE	/verified-host/:id	Delete your verification by id (other/non-existent → 404)

Fields of the VerifiedHost object: id, host, method (dns / http / auto-private), verifiedAt, expiresAt. The token is not returned in the response.

See also

• Port scanning — main consumer of verified-host: verified hosts are scanned in accelerated mode.
• Active monitors and port monitors — other ways to track host and port availability.