# Activate custom domain

Start custom domain certificate validation after completing DNS setup.

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

`POST /app/dashboards/{id}/domains/custom-domain/activate`

Starts certificate validation after the customer has created the required DNS CNAME record.

This endpoint is only valid when the dashboard's `customDomainStatus` is `awaiting_dns`. Calling it transitions the status to `validating` and queues an async provisioning job. Requires **admin** role and the **Custom Domain** feature entitlement.

***

## Custom domain lifecycle
| Status         | When                                                                                                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `awaiting_dns` | Custom domain saved; create the CNAME record and call this endpoint to start validation. Times out after 72 hours if never activated.                                 |
| `validating`   | Activation requested; certificate provisioning in progress (up to 72 hours from activation).                                                                          |
| `active`       | Certificate validated; custom domain is fully functional. Re-checked every 15 minutes.                                                                                |
| `failed`       | Setup or validation failed (72-hour timeout or rejection). Use [Delete custom domain](/docs/api/status-dashboards/dashboards/domains/custom-domain/delete) and retry. |
| `removing`     | Infrastructure cleanup in progress after a remove request.                                                                                                            |

The **72-hour validation clock** starts when you call this endpoint, not when the custom domain is first saved. If you save a domain but never activate it, status changes to `failed` after 72 hours from save.

After an **active** domain loses its CNAME record, status returns to `awaiting_dns`. Restore DNS and call this endpoint again to resume validation — existing provisioning configuration is retained when possible.

***

## Path parameters
| Parameter | Description                |
| --------- | -------------------------- |
| `id`      | The UUID of the dashboard. |

***

## Request
See [API Basics](/docs/api) for required headers.

This endpoint takes no request body.

***

## Sample request
```bash
curl -X POST https://api.statusdashboard.com/app/dashboards/a1b2c3d4-e5f6-7890-abcd-ef1234567890/domains/custom-domain/activate \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "message": "Custom domain activation started",
  "status": "validating",
  "customDomain": "status.acme.com"
}
```

***

## Error responses
| Status | When                                                                           |
| ------ | ------------------------------------------------------------------------------ |
| `400`  | Dashboard has no custom domain, or `customDomainStatus` is not `awaiting_dns`. |
| `403`  | Insufficient permissions.                                                      |
| `404`  | Dashboard not found or does not belong to the caller's organization.           |