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

# Custom domains and managed SSL

> How white-label domains work end to end — CNAME verification, automatic certificate issuance, the status lifecycle, and the organization API fields that report provisioning state.

# 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.

<Note>
  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](/troubleshooting/email-dns-drift) page.
  This page covers dashboard and public-page hostnames only.
</Note>

## 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:

```bash theme={null}
# Register the hostname (response carries the cname_target to publish)
curl -X POST "https://orbit.devotel.io/api/v1/organization/domains" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.acme.example"}'

# After the CNAME is published, start verification
curl -X POST "https://orbit.devotel.io/api/v1/organization/domains/<domain_id>/verify" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

# Poll status (list)
curl "https://orbit.devotel.io/api/v1/organization/domains" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

Every domain object returned by these endpoints carries:

| Field                     | Meaning                                                                  |
| ------------------------- | ------------------------------------------------------------------------ |
| `status`                  | `pending`, `verifying`, `active`, or `failed`                            |
| `cname_target`            | The DNS value your CNAME record must carry                               |
| `cname_verified_at`       | When the CNAME check passed (null before)                                |
| `ssl_cert_provisioned_at` | When the managed certificate finished provisioning (null until `ACTIVE`) |
| `ssl_cert_secret_name`    | Reference to the stored certificate material                             |
| `error`                   | The last issuance failure, when one occurred                             |

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

* [Organization API reference](/api-reference/organization) — full envelope
  and schema for the organization domain endpoints
* [Subaccount and organization model](/concepts/subaccount-organization-model) —
  how white-label domains attach to subaccounts and organizations
* [Email DNS drift and recovery](/troubleshooting/email-dns-drift) — the
  same verification loop for email-sending domains (SPF, DKIM, DMARC)