Domain Validation

Before ScaiDNS will serve DNS for a zone, you must prove you control that domain. This prevents anyone from creating example.com and immediately stealing traffic if delegation is later pointed at the ScaiDNS nameservers.

Validation happens once, at zone creation. After it completes, the zone is permanently marked active — you don't re-validate unless you've let it lapse.

How it works#

When you create a domain (POST /api/v1/domains/), the API:

1. Inserts a row in MariaDB with status pending_validation.
2. Generates a challenge token.
3. Returns instructions for publishing a TXT record at your current DNS provider.

You then publish the TXT record, call POST /api/v1/domains/{id}/validation/check, and ScaiDNS queries DNS directly — bypassing caches — to confirm the record is live.

The challenge#

Fetch the challenge with:

1
2

curl https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/validation \
  -H "X-API-Key: $SCAIDNS_API_KEY"

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "validation_type": "txt_record",
  "status": "pending",
  "dns_record": {
    "name": "_scaidns-verify.example.com",
    "type": "TXT",
    "value": "scaidns-verify=a1b2c3d4e5f6..."
  },
  "expires_at": "2026-04-26T10:42:00Z"
}

Publish that TXT record at your current DNS provider. The domain's NS delegation doesn't need to point at ScaiDNS yet — validation queries whatever nameservers are authoritative today.

How ScaiDNS checks#

When you trigger a check:

1
2

curl -X POST https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/validation/check \
  -H "X-API-Key: $SCAIDNS_API_KEY"

ScaiDNS:

1. Looks up the NS records for your domain using public recursive resolvers (1.1.1.1, 8.8.8.8, 9.9.9.9). This avoids your local resolver's cache.
2. Resolves each NS hostname to an IP.
3. Queries each authoritative nameserver directly for the _scaidns-verify.<domain> TXT record.
4. Compares the value to the expected challenge.

Querying authoritative nameservers directly bypasses caching. This is why validation usually works within seconds of publishing the TXT record — there's no intermediate cache to invalidate.

If authoritative nameservers can't be discovered (e.g., the domain itself doesn't exist in DNS yet), ScaiDNS falls back to public resolvers. A domain that isn't registered or hasn't been delegated won't validate until it resolves somewhere.

Response#

On success:

1

{"is_valid": true, "message": "Domain validated"}

The domain's status flips to active and the PowerDNS zone is created.

On failure:

1
2
3
4

{
  "is_valid": false,
  "message": "TXT record found but value doesn't match. Expected: scaidns-verify=a1b2c3..."
}

Common failure messages and what they mean:

When validation fails repeatedly#

Check propagation. After publishing a TXT record, your own resolver may cache the absence for the original negative TTL. Use dig @1.1.1.1 TXT _scaidns-verify.<domain> to check from a fresh resolver.

Check you wrote it at the right place. The record must be at _scaidns-verify.<domain>, not <domain> itself, not a subdomain. Watch for providers that append the zone automatically — enter _scaidns-verify as the record name, not _scaidns-verify.example.com.

Check the challenge didn't expire. Challenges expire (default 72 hours). Fetch a fresh one via POST /api/v1/domains/{id}/validation to regenerate.

Check the domain resolves at all. dig NS <domain> should return your current nameservers. If it returns NXDOMAIN, the domain isn't registered or delegation is broken at the registrar.

Re-validation#

Once active, a zone doesn't re-validate on every change. However, you can cancel and restart validation if something's wrong:

1
2
3
4
5
6
7
8
9

# Cancel current validation
curl -X DELETE https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/validation \
  -H "X-API-Key: $SCAIDNS_API_KEY"

# Start a new one
curl -X POST https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/validation \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"validation_type": "txt_record"}'

Nameserver validation (alternative)#

Some deployments support NS-record validation in addition to TXT. In this mode, ScaiDNS confirms the domain's NS records at the parent zone match the ScaiDNS nameservers. This is useful for zones being migrated in — delegation and validation happen in one step.

NS validation requires platform operator configuration. If enabled, create the challenge with {"validation_type": "nameservers"}.

Bypassing validation#

Users with the validation_bypass permission can create zones that skip validation entirely. This is intended for:

• Internal zones that don't exist on the public internet (private or split-horizon).
• Migrations from another ScaiDNS-managed system where ownership is already established.
• Automated pipelines that manage the delegation separately.

Grant validation_bypass sparingly — it's a trust boundary.

What's next#

• Managing Domains — zone CRUD with validation.
• Domain Validation reference — the endpoint surface.
• Errors — interpreting validation error responses.