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

# Custom Domains

> White-label your scan URLs — replace nearnode.io with your own domain.

Custom domains let you replace `nearnode.io/v/slug` with `link.yourbrand.com/v/slug`. Your printed QR codes and NFC tags display your brand, not ours. Existing tags continue to work on both domains — no reprinting required.

<Note>
  Custom domains are available on the **Pro** plan (1 domain) and **Enterprise** plan (unlimited domains).
</Note>

## Setup

<Steps>
  <Step title="Add Your Domain">
    Navigate to **Settings → Domains** in the Dashboard. Enter your subdomain (e.g., `link.yourbrand.com`).
  </Step>

  <Step title="Configure DNS">
    Add two DNS records at your domain registrar:

    **CNAME Record** — routes traffic to NearNode's edge:

    ```
    CNAME  link.yourbrand.com  →  cname.nearnode.io
    ```

    **TXT Record** — proves domain ownership:

    ```
    TXT  _vidiai-verify.link.yourbrand.com  →  your-verification-token
    ```

    The verification token is displayed in the Dashboard after adding the domain.
  </Step>

  <Step title="Verify">
    Click **Verify** in the Dashboard. NearNode checks your DNS records and activates the domain. Propagation typically takes 5–30 minutes.
  </Step>

  <Step title="Live">
    Once verified, all your nodes automatically resolve on both `nearnode.io` and your custom domain. No node reconfiguration needed.
  </Step>
</Steps>

<Info>
  **Ops Tip:** You can verify domain setup via the Dashboard — no API calls required. The status indicator shows `Pending`, `Verified`, or `Failed` with diagnostic details.
</Info>

## SSL / TLS

SSL certificates are provisioned automatically via Let's Encrypt within minutes of domain verification. No manual certificate management required.

* **Protocol:** TLS 1.2 and 1.3
* **Certificate renewal:** Automatic, 30 days before expiry
* **HSTS:** Enabled by default

## API Configuration

```bash theme={null}
curl -X POST https://nearnode.io/api/v1/domains \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "link.yourbrand.com"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": "dom_abc123",
    "domain": "link.yourbrand.com",
    "verified": false,
    "verification_token": "v_8a3f2b1c9d4e5f6a7b8c",
    "cname_target": "cname.nearnode.io",
    "created_at": "2026-02-09T14:30:00.000Z"
  }
}
```

## Multiple Domains

Enterprise accounts can configure multiple custom domains per workspace — useful for multi-brand portfolios or regional deployments.

| Domain             | Brand   | Region |
| ------------------ | ------- | ------ |
| `link.brand-a.com` | Brand A | Global |
| `nfc.brand-b.de`   | Brand B | DACH   |
| `scan.brand-c.fr`  | Brand C | France |

All domains resolve the same node inventory. The scan URL domain is recorded in analytics events, allowing you to segment traffic by brand.

## Domain Verification API

Check verification status programmatically:

```bash theme={null}
curl https://nearnode.io/api/v1/domains/dom_abc123 \
  -H "Authorization: Bearer sk_live_..."
```

```json theme={null}
{
  "data": {
    "id": "dom_abc123",
    "domain": "link.yourbrand.com",
    "verified": true,
    "verified_at": "2026-02-09T14:35:00.000Z",
    "ssl_status": "active"
  }
}
```

## Removing a Domain

```bash theme={null}
curl -X DELETE https://nearnode.io/api/v1/domains/dom_abc123 \
  -H "Authorization: Bearer sk_live_..."
```

<Warning>
  Removing a verified domain immediately stops resolving scan URLs on that domain. If you have printed QR codes or written NFC tags with the custom domain, those assets will stop working. The `nearnode.io` URLs remain unaffected.
</Warning>

## Troubleshooting

| Issue                           | Cause                            | Fix                                                                                                 |
| ------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- |
| Verification stuck on `Pending` | DNS not propagated               | Wait 30 minutes, then retry. Use `dig TXT _vidiai-verify.link.yourbrand.com` to confirm.            |
| `CNAME conflict`                | Existing A/AAAA record           | Remove the A/AAAA record before adding the CNAME.                                                   |
| SSL not provisioning            | CNAME not resolving              | Verify the CNAME points to `cname.nearnode.io` and is not proxied (e.g., disable Cloudflare proxy). |
| Redirect loop                   | Cloudflare SSL set to "Flexible" | Set Cloudflare SSL mode to "Full (strict)" or disable proxy.                                        |