Skip to main content
Custom domains let you serve the Truthlocks verification portal and console from your own domain. Instead of verify.truthlocks.com, your users see verify.yourdomain.com.
Custom domains are available on all plans. Navigate to Settings > Domains in the console to get started.

​
Domain types

Truthlocks supports two types of custom domains:
TypePurposeExample
VerificationPublic-facing verification portal where recipients and auditors verify attestationsverify.yourdomain.com
ConsoleAdministrative console for your teamconsole.yourdomain.com
You can configure one or both types depending on your needs.

​
Setting up a custom domain

1

Open domain settings

Navigate to Settings > Domains in the console.
2

Add a domain

Click Add Domain, select the domain type (Verification or Console), and enter the hostname you want to use (e.g., verify.yourdomain.com).
3

Add the DNS record

Truthlocks generates a unique verification token for your domain. Add a TXT record to your DNS configuration:
FieldValue
TypeTXT
Name_truthlocks-verify
ValueThe verification token shown in the console
Copy the token using the Copy button next to it.
4

Verify the domain

After adding the DNS record, click Verify DNS Record in the console. Truthlocks checks for the TXT record and updates the domain status.
DNS propagation can take up to 48 hours, though most providers propagate within minutes. If verification fails, wait a few minutes and try again.

​
Domain statuses

Each domain progresses through three statuses:
StatusMeaning
PendingThe domain has been added but the DNS record has not been verified yet.
VerifiedThe DNS TXT record was found and validated. The domain becomes active automatically.
ActiveThe domain is live and serving traffic for your tenant.

​
Managing domains via the API

You can add, list, and verify custom domains programmatically.

​
List domains

Request
GET /v1/settings/domains
X-API-Key: tl_live_...
Response
{
  "domains": [
    {
      "id": "dom_abc123",
      "tenant_id": "tn_xyz789",
      "type": "VERIFY",
      "hostname": "verify.acme.com",
      "status": "ACTIVE",
      "verification_token": "tl-verify-abc123def456",
      "verified_at": "2026-03-25T14:30:00Z",
      "created_at": "2026-03-25T14:00:00Z"
    }
  ]
}

​
Add a domain

Request
POST /v1/settings/domains
X-API-Key: tl_live_...
Content-Type: application/json

{
  "type": "VERIFY",
  "hostname": "verify.acme.com"
}
The type field accepts VERIFY for verification domains or CONSOLE for console domains. The response includes the verification_token you need for DNS setup.

​
Verify a domain

Request
POST /v1/settings/domains/{domain_id}/verify
X-API-Key: tl_live_...
Returns the updated domain object. If the DNS record is not found, the status remains PENDING.

​
Example: full setup

# 1. Add the domain
curl -X POST https://api.truthlocks.com/v1/settings/domains \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"type": "VERIFY", "hostname": "verify.acme.com"}'

# 2. Add the TXT record to your DNS (using your DNS provider)
# Name:  _truthlocks-verify
# Value: <verification_token from response>

# 3. Verify the domain
curl -X POST https://api.truthlocks.com/v1/settings/domains/dom_abc123/verify \
  -H "X-API-Key: tl_live_..."

​
Troubleshooting

​
Verification keeps failing

  1. Confirm the TXT record name is exactly _truthlocks-verify (some providers append the domain automatically — check for duplicates like _truthlocks-verify.yourdomain.com.yourdomain.com).
  2. Wait for DNS propagation. Use dig TXT _truthlocks-verify.yourdomain.com to confirm the record is visible.
  3. Ensure the TXT value matches the token shown in the console exactly, with no extra spaces.

​
Domain is verified but not active

Verified domains transition to Active automatically. If the status does not update, refresh the page or re-fetch via the API.

Custom branding

Upload logos and set brand colors for verification pages and emails.

Email delivery

Configure custom email senders and SMTP servers.