Custom Domains

Serve VeriSwarm badges and widgets from your own domain instead of veriswarm.ai. This gives your trust badges a branded appearance and keeps all user-facing URLs under your control.

---

What Changes After Setup

Once a custom domain is verified:

• Badge URLs can use your domain: https://trust.example.com/v1/badge/my-agent.svg
• Widget embeds resolve under your domain
• Agent profile links can reference your domain

The standard veriswarm.ai URLs continue to work alongside your custom domain.

---

Setup Process

Step 1: Choose Your Subdomain

Pick a subdomain like trust.example.com or agents.example.com. You cannot use a bare apex domain (e.g., example.com) -- it must be a subdomain that supports CNAME records.

Step 2: Register the Domain

Via the Dashboard

Navigate to Account > Settings > Custom Domain and enter your subdomain.

Via the API

curl -X POST https://veriswarm.ai/v1/public/providers/custom-domain \
  -H "x-account-access-token: YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "trust.example.com"
  }'

Response:

{
  "status": "pending_verification",
  "domain": "trust.example.com",
  "cname_target": "custom.veriswarm.ai",
  "instructions": "Add a CNAME record: trust.example.com → custom.veriswarm.ai"
}

Step 3: Add the DNS Record

In your DNS provider's control panel, create a CNAME record:

Type	Name	Target	TTL
CNAME	trust	custom.veriswarm.ai	300 (or Auto)

Example configurations by DNS provider:

Cloudflare:

Type:    CNAME
Name:    trust
Target:  custom.veriswarm.ai
Proxy:   DNS only (gray cloud)

Route 53 (AWS):

Record name:  trust.example.com
Record type:  CNAME
Value:        custom.veriswarm.ai
TTL:          300

Google Domains / Cloud DNS:

Host name:    trust
Type:         CNAME
Data:         custom.veriswarm.ai.
TTL:          300

Note the trailing dot after custom.veriswarm.ai. in some DNS providers -- this indicates a fully qualified domain name.

Step 4: Verify

DNS propagation can take anywhere from a few seconds to 48 hours, though most changes propagate within 5 minutes.

Via the Dashboard

Click Verify Domain. The system checks the CNAME record in real time.

Via the API

curl -X POST https://veriswarm.ai/v1/public/providers/custom-domain/verify \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Success:

{
  "status": "verified",
  "domain": "trust.example.com"
}

Not yet propagated:

{
  "status": "cname_not_found",
  "domain": "trust.example.com",
  "detail": "CNAME does not point to custom.veriswarm.ai"
}

If verification fails, wait a few minutes and try again. Use dig trust.example.com CNAME to check propagation from your terminal.

---

Checking Your Configuration

curl https://veriswarm.ai/v1/public/providers/custom-domain \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Response:

{
  "domain": "trust.example.com",
  "verified": true,
  "cname_target": "custom.veriswarm.ai"
}

---

Removing a Custom Domain

curl -X DELETE https://veriswarm.ai/v1/public/providers/custom-domain \
  -H "x-account-access-token: YOUR_SESSION_TOKEN"

Response:

{
  "status": "removed"
}

After removal, all traffic reverts to the default veriswarm.ai domain. You should also remove the CNAME record from your DNS provider to keep your DNS clean.

---

Domain Uniqueness

Each custom domain can only be associated with one VeriSwarm workspace. If you try to register a domain already in use by another workspace, you will receive a 409 Conflict error.

---

Troubleshooting

Issue	Solution
Verification fails immediately	Check that the CNAME target is exactly custom.veriswarm.ai (no typos, no trailing path)
Verification fails after waiting	Run dig your-subdomain CNAME to confirm DNS propagation. Some providers cache aggressively.
SSL certificate errors	VeriSwarm provisions TLS certificates automatically after verification. Allow up to 15 minutes for certificate issuance.
Cloudflare proxy enabled	Set the CNAME to DNS only (gray cloud). Cloudflare's proxy can interfere with verification.