# Custom Domain

Serve your status dashboard from your own domain with automatic SSL.

Source: https://statusdashboard.com/docs/status-dashboards/domains/custom-domain

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

A custom domain serves your status dashboard from a hostname you control, such as `status.yourcompany.com`. Add the required DNS record and wait for certificate validation to go live on your brand URL.

***

## Format requirements
The **Domains** section lets you serve your status dashboard from your own domain (e.g., `status.acme.com`) instead of your default `statusdashboard.io` [subdomain](/docs/status-dashboards/domains/subdomain).

| Requirement             | Details                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Must be a subdomain** | Apex (root) domains like `acme.com` are not supported. You must use at least one subdomain label, e.g. `status.acme.com`.             |
| **Maximum length**      | 253 characters total (the full hostname).                                                                                             |
| **Label characters**    | Each dot-separated label may contain lowercase letters (`a–z`), digits (`0–9`), and hyphens (`-`). Uppercase letters are not allowed. |
| **Label format**        | Each label must start and end with a letter or digit — leading or trailing hyphens are not allowed.                                   |

**Valid examples:** `status.acme.com`, `us.status.acme.com`, `status-prod.acme.com`

**Invalid examples:** `acme.com` (apex domain), `-status.acme.com` (leading hyphen), `status-.acme.com` (trailing hyphen)

## Prerequisites
* Access to your domain's DNS provider to create a CNAME record.
* A subdomain you control (e.g., `status.acme.com`).

## Setup
### Step 1 — Enter your custom domain
1. Open the dashboard settings and go to the **Domains** section.
2. Enter the full hostname you want to use (e.g., `status.acme.com`).
3. Click **Save Dashboard**.

The domain status changes to **Awaiting DNS**. No traffic routing or certificate work begins yet — this step records your intended domain.

### Step 2 — Create a CNAME record
The **Domains** section displays the CNAME record to add in your DNS provider:

| Type  | Name                                               | Value                   |
| ----- | -------------------------------------------------- | ----------------------- |
| CNAME | `status.acme.com` *(your custom domain)* | `db.statusdashboard.io` |

The target is always `db.statusdashboard.io`. Add this record in your DNS provider (e.g., Cloudflare, Route 53, GoDaddy). DNS propagation typically takes a few minutes but can take up to 24 hours.

### Step 3 — Confirm your DNS record
Once the CNAME is in place, return to the **Domains** section and click **DNS Record Created**.

> **Important:**
>    Do not click this until the CNAME is actually in place. Certificate validation requires the DNS record to be resolvable.

### Step 4 — Wait for certificate validation
The domain status changes to **Validating**. StatusDashboard automatically provisions and validates an SSL/TLS certificate for your domain. No action is required.

**Typical time: a few minutes to a few hours.** The **72-hour clock** starts when you click **DNS Record Created** (not when you first save the domain). If provisioning does not complete within 72 hours, or if the certificate authority rejects the request, the status changes to **Failed** and the domain shows **⚠ Provisioning failed** along with a reason. Remove the domain and try again after confirming your CNAME record is correct.

If you save a custom domain but never click **DNS Record Created**, the setup also times out after 72 hours from when the domain was first saved.

### Step 5 — Active
When validation completes, the status changes to **Active**. Your status dashboard is live at your custom domain with HTTPS fully configured.

The CNAME record must remain in place permanently. Removing it breaks traffic routing and causes SSL/TLS certificate renewal to fail.

> **Subdomain redirect:**
>    Once your custom domain is active, visitors to your original 
>   `statusdashboard.io`
>    subdomain are automatically redirected to your custom domain.

## Status reference
| Status           | Meaning                                                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Awaiting DNS** | You've saved a custom domain. Create the CNAME and click **DNS Record Created** to proceed.                                                                    |
| **Validating**   | Certificate provisioning is in progress. No action needed.                                                                                                     |
| **Active**       | Your custom domain is live and fully secured with HTTPS. The platform re-checks your CNAME and certificate every 15 minutes.                                   |
| **Failed**       | Provisioning failed — the domain shows **⚠ Provisioning failed** with a reason. Remove the domain and try again after confirming your CNAME record is correct. |
| **Removing**     | Infrastructure cleanup is in progress after a remove request.                                                                                                  |

While a domain is **Validating** or **Active**, use **Refresh Status** in the Domains section to reload the latest state from the platform. Automatic checks also run every 15 minutes.

## Notifications
Status changes appear in the **Domains** section of your dashboard settings. Organization **admins** also receive email for high-signal outcomes (success, terminal failure, and verification loss after activation).

| Event                                  | In the portal                                                                               | Email to org admins                                       |
| -------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Domain becomes active**              | Status changes to **Active**                                                                | Confirmation email when the SSL certificate is issued     |
| **Provisioning fails**                 | Status changes to **Failed** with **⚠ Provisioning failed** and a reason               | Failure email with the reason and next steps              |
| **Verification lost after activation** | Status changes to **Awaiting DNS** with an error message                                    | Email explaining what was detected and how to restore DNS |
| **During validation or health checks** | Status badge updates on the 15-minute schedule; use **Refresh Status** for the latest state | No email                                                  |
| **Brief DNS issues (grace period)**    | Status stays **Active** for about 45 minutes while checks retry                             | No email                                                  |

Emails are sent to all organization admins. They are best-effort and do not affect whether the domain status updates in the portal.

## SSL/TLS certificates
Certificates are provisioned and managed automatically. There is nothing to purchase, configure, or upload.

* **Provisioning** happens automatically when you confirm your DNS record.
* **Renewal** is handled automatically before expiry — your CNAME record must remain in place for renewal to succeed.
* **Scope** — the certificate covers your specific custom domain only.

## Removing a custom domain
1. Open the **Domains** section in dashboard settings.
2. Click **Remove Custom Domain** and confirm.

Infrastructure cleanup happens in the background (typically within a few minutes). The status shows **Removing** during this window. Once removed, your dashboard is accessible only via its standard `statusdashboard.io` subdomain. You can add a different custom domain at any time.

## Troubleshooting
**The domain has been in "Validating" for a long time**

Check that your CNAME record is correctly configured and has propagated. Tools such as [dnschecker.org](https://dnschecker.org) can confirm propagation across global DNS servers. Validation runs on a cycle — once the record is confirmed to be in place, it will complete on its own.

**The domain shows "Failed"**

Validation did not complete within 72 hours. Remove the domain, verify your CNAME is correctly set, and add it again. See [Notifications](#notifications) for when admins receive email.

**I removed the CNAME record by mistake**

While your domain is **Active**, StatusDashboard checks every 15 minutes that your CNAME record and certificate are still valid. Brief DNS issues are tolerated for about 45 minutes before the status changes.

If verification is lost, status changes to **Awaiting DNS** with a message that verification was lost. Your custom domain URL may stop working, but your `statusdashboard.io` subdomain continues to serve the dashboard. Re-add the CNAME record with the target shown in the Domains tab, then click **DNS Record Created** to resume validation. Your existing configuration is retained — you do not need to remove and re-add the domain unless validation still fails after restoring DNS. See [Notifications](#notifications) for when admins receive email.