Skip to main content

Verify your domain

Registering a domain tells Appilot which app a hostname belongs to. Verifying it proves you control that hostname. The two are separate steps, and a domain that shows Registered is not yet verified.

Verification is the anti-abuse control on the credentials that claim traffic. Tenant resolution is by domain, so minting a live widget key for a hostname nobody has proved they control would make claiming someone else's traffic free.

What verification unlocks​

Unlocked by verificationWorks without it
Minting a wk_live_ widget key that covers the hostnameThe keyless widget path on a registered domain
The site adapter lookup, which serves the per-domain detection configurationExtension turns for members of the owning organization
Test keys on loopback addresses

So a domain you cannot verify is still usable: your users get the assistant, the knowledge, the views and the action plans. What you cannot do is mint a live widget key for it or ship a site adapter to it.

Publish the record​

  1. In the Backoffice, open Apps, find the domain, and open Domain verification. The dialog shows both halves of the record.

  2. Create a TXT record in the DNS zone of that hostname:

    Name:  _appilot-verify.app.example.com
    Value: appilot-domain-verify=<the token the dialog shows>

    The token is derived per domain, so every hostname gets its own record. A subdomain needs its own record; verifying example.com does not verify app.example.com.

  3. Wait for the record to propagate. Minutes usually, up to 48 hours in the worst case.

  4. Choose Verify now. Appilot resolves the TXT record and marks the domain verified. If the record is not visible yet, the dialog says so and you can check again at any time. Nothing is lost by trying early.

From an MCP client​

The same two steps, without leaving your assistant:

Show me the verification record for app.example.com, then verify it.

The provisioning tools return the record when the domain is created, so a fresh app tells you what to publish before you ask.

Over the API​

curl https://api.appilot.space/apps/domains/42/verification \
  -H "Authorization: Bearer <token>"
# → { "verification_status": "unverified",
#     "dns_record_name": "_appilot-verify.app.example.com",
#     "dns_record_value": "appilot-domain-verify=..." }

curl -X POST https://api.appilot.space/apps/domains/42/verify \
  -H "Authorization: Bearer <token>"
# → { "verified": true }

The check reads live DNS every time, so it costs nothing to re-run and there is no queue to wait on.

When you cannot publish a record​

This is the normal case for a hosted application you use but do not own: a SaaS tenant on the vendor's hostname, an ERP your provider operates, a portal run by another department. You do not control that zone, and nobody is going to add a TXT record to it for you.

Register the hostname anyway and skip verification. What you get:

  • The extension serves it in full. Views, controls, forms, action plans and knowledge all apply for members of your organization, on an unverified domain.
  • The keyless widget path, if the vendor ever lets you embed a script, resolves the tenant from the domain without a key.

What you do not get is the live widget key and the site adapter. If you need a site adapter on a hostname you cannot verify, talk to us: it is a per-hostname decision, not something a flag switches on.

Two further constraints are worth knowing before you plan around this hostname:

  • A hostname belongs to exactly one organization. On a shared SaaS host, the first organization to register it holds it, and a second one is refused. Use the tenant-specific hostname your vendor gives you (acme.vendor.com) where one exists.
  • Users on that hostname must be members of the organization that registered it, or their turns are refused.

Checking status​

The domain list shows the status per hostname. A verified domain keeps its status; there is no re-verification schedule, and removing the TXT record later does not revoke it. Delete the domain when you stop using the hostname.