Activate custom domain — StatusDashboard Docs

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 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 for required headers.

This endpoint takes no request body.

Sample request

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

{
  "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.