> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Set up branded URLs for your verification portal and console with custom domain configuration and DNS verification.

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`.

<Info>
  Custom domains are available on all plans. Navigate to **Settings > Domains**
  in the console to get started.
</Info>

## Domain types

Truthlocks supports two types of custom domains:

| Type             | Purpose                                                                             | Example                  |
| :--------------- | :---------------------------------------------------------------------------------- | :----------------------- |
| **Verification** | Public-facing verification portal where recipients and auditors verify attestations | `verify.yourdomain.com`  |
| **Console**      | Administrative console for your team                                                | `console.yourdomain.com` |

You can configure one or both types depending on your needs.

## Setting up a custom domain

<Steps>
  <Step title="Open domain settings">
    Navigate to **Settings > Domains** in the console.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Add the DNS record">
    Truthlocks generates a unique verification token for your domain. Add a TXT
    record to your DNS configuration:

    | Field     | Value                                       |
    | :-------- | :------------------------------------------ |
    | **Type**  | `TXT`                                       |
    | **Name**  | `_truthlocks-verify`                        |
    | **Value** | The verification token shown in the console |

    Copy the token using the **Copy** button next to it.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  DNS propagation can take up to 48 hours, though most providers propagate
  within minutes. If verification fails, wait a few minutes and try again.
</Tip>

## Domain statuses

Each domain progresses through three statuses:

| Status       | Meaning                                                                              |
| :----------- | :----------------------------------------------------------------------------------- |
| **Pending**  | The domain has been added but the DNS record has not been verified yet.              |
| **Verified** | The DNS TXT record was found and validated. The domain becomes active automatically. |
| **Active**   | The 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

```http Request theme={null}
GET /v1/settings/domains
X-API-Key: tl_live_...
```

```json Response theme={null}
{
  "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

```http Request theme={null}
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

```http Request theme={null}
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

```bash theme={null}
# 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.

## Related

<CardGroup cols={2}>
  <Card title="Custom branding" icon="palette" href="/guides/enterprise-branding">
    Upload logos and set brand colors for verification pages and emails.
  </Card>

  <Card title="Email delivery" icon="envelope" href="/security/email-delivery">
    Configure custom email senders and SMTP servers.
  </Card>
</CardGroup>