Skip to main content

​
Custom domains and managed SSL

A custom domain lets you serve your Devotel Orbit dashboard from your own hostname — app.acme.example instead of the shared orbit.devotel.io address. You register the hostname, point a CNAME record at the platform, and the platform issues and maintains a TLS certificate for it. No certificate upload, and nothing to renew. This page covers the custom domain model: which hostnames your organization can register, how the verification and certificate pipeline works, what each lifecycle status means, and where the API exposes provisioning state. Register and manage domains in the dashboard under Settings > Branding > Domains, or through the organization domain endpoints.
Email-sending domains are a separate pipeline with their own TXT-record verification (SPF, DKIM, DMARC). For those, work the email DNS drift and recovery page. This page covers dashboard and public-page hostnames only.

​
Two kinds of custom domain

  • Organization (white-label) domains serve your dashboard. Every request to your hostname resolves to your subaccount or organization, and the platform serves the branded experience — sign-in, branding, public links — from your own address. Subaccount-level registration lives under the subaccounts surface; organization-level registration uses POST /api/v1/organization/domains. Both follow the same lifecycle.
  • Public links and landing pages. White-label short links, hosted landing pages, and public join URLs inherit the organization domain of the owning org, so customers never see the platform hostname.
Either way the model is the same: one registered hostname, one CNAME check, one managed certificate.

​
Lifecycle of a registered domain

A registered domain moves through four statuses, visible in the dashboard domains list and in the status field of every domain API response:
  1. pending — the domain is registered. Add the DNS record and request verification from this state.
  2. verifying — the CNAME matched and certificate issuance has started.
  3. active — the certificate reached ACTIVE and the domain serves traffic over HTTPS.
  4. failed — the certificate authority reported a terminal failure. The error field carries the reason.
Delete a domain at any point to remove it: DELETE /api/v1/organization/domains/:domainId. Until deletion, the platform keeps retrying issuance in the background and clears the error field when it recovers.

​
DNS contract

Each registered domain has exactly one DNS requirement: a CNAME record pointing the hostname at the platform ingress address. The exact value your CNAME must carry is returned as cname_target in the claim response and on every subsequent read of the domain. Read it from the API rather than relying on remembered instructions, so the value always matches the ingress your region validates against. Start the DNS check with POST /api/v1/organization/domains/:domainId/verify. Resolution is re-checked, and on match the record flips to verifying and certificate issuance starts. If the check is inconclusive — a resolver timeout or no answer — the status stays pending with no error recorded; request verification again after the TTL settles. You are free to use any registrar or DNS provider, and flattened or chained CNAMEs work as long as the chain ends at the expected ingress address.

​
How certificates are issued

Once the CNAME matches, the platform requests a managed certificate for your hostname from a domain-validated managed-certificate authority. Managed certificates sit in a PROVISIONING phase for about 15 minutes while the issuer validates DNS, then reach ACTIVE. The first request starts issuance synchronously; a scheduled poll then re-checks the certificate phase until it turns ACTIVE, at which point your domain record flips to active. You do not need to re-run verification while this is in flight. Where issuance stalls — usually the CNAME record removed mid-provisioning, or an edge in the serving path that needs an operator touch — the poll keeps the domain in verifying rather than expiring the request. If the issuer reports a terminal failure the domain flips to failed and the error field on the domain record describes the cause, so the reason is readable in the dashboard instead of being inferred.

​
Reading provisioning state from the API

Use a single endpoint for the whole loop:
Every domain object returned by these endpoints carries: Poll ssl_cert_provisioned_at (or status) to gate a rollout; treat it as additive when consuming the response, as the domain object may gain fields over time.

​
Security boundary

Certificates route through the platform’s managed pipeline because a managed certificate is the full alternative to uploading your own. The platform requests, attaches, and renews the certificate over the lifetime of the record — nothing that lives in your organization contains private key material, and no one in the organization uploads PEM files on a rotation calendar. The ssl_cert_secret_name field points at the stored certificate material; an operator step like rotation does not appear in the org record and does not change DNS. This is also why there is no upload-your-own-certificate surface.

​
Troubleshooting checklist

  1. Domain is pending and your record is already published — run POST /api/v1/organization/domains/:domainId/verify again; DNS caches answer by TTL and the check is inconclusive until propagation settles.
  2. Domain is verifying past ~15 minutes — confirm the CNAME still resolves end-to-end to cname_target; a record removed or chained away mid-provisioning stalls issuance.
  3. Domain is verifying with a green DNS check — this is a platform-side stall; contact support with the domain id.
  4. Domain is failed — read the error field, correct the cause, and request verification again.
  5. Dashboard checks: re-run Verify from the domains list if the CNAME was published after registration.

​
See also