# Company domains

> Give apps friendly hostnames under a DNS zone your company owns.

Source: https://diakrin.com/docs/domains

Give an app a friendly address such as `crm.apps.example.com` under a DNS zone your company already owns. IT registers the zone once; builders then request names under it.

```steps
Connect a zone | Owner, admin or Technical administrator | Under **Infrastructure → Domains**, create a scoped Cloudflare token from the pre-filled link, paste it, pick the zone (optionally a sub-zone such as `apps.example.com`) and select **Connect and verify**.
Verify ownership | Diakrin | Registrar zones get the `_diakrin-verify` TXT record written and checked against public DNS as part of connecting; manual zones add it by hand.
Request a hostname | Builder | Ask for a label such as `crm` under the verified zone from the app's **Company hostname** card.
Approve and publish | Technical owner | Approval resolves the app's endpoint and publishes a CNAME, or shows the record to add by hand.
Check DNS | Builder or technical owner | **Check DNS** reports live only when the name resolves to the target.
Certificate and edge | Diakrin, then the next deployment | On AWS, approval also requests a certificate for the exact name in your account and publishes its validation record; the next deployment serves HTTPS on the name. On Google Cloud, see [the current limit](#what-this-does-not-cover).
```

## Connect and verify a zone

Owners, IT administrators and Technical administrators connect a company DNS zone once under **Infrastructure → Domains**, for example `apps.example.com`.

**Cloudflare (guided).** Select **Create token in Cloudflare**: the Cloudflare token form opens with the two permissions Diakrin needs already selected (DNS edit and zone read). Limit the token to the one zone you are connecting, create it and paste it into Diakrin. **Find zones** lists the zones that token can see; pick one and, preferably, a sub-zone label such as `apps` so generated apps stay under `apps.example.com`. **Connect and verify** stores the sealed token, writes the `_diakrin-verify` TXT record and checks public DNS in one step. The token is encrypted before it reaches the database and is never shown again.

**Amazon Route 53 and GoDaddy.** Enter the zone name, its hosted zone or registered domain, and an API credential scoped to that zone. Connecting also writes and checks the verification record.

**Manual records.** Enter the zone name only. Diakrin shows the TXT record to add at any registrar; select **Verify ownership** once it has propagated.

Every zone is checked against public DNS, and only the actual resolver answer changes the zone state.

## Request a hostname for an app

Builders open an app and choose **Company hostname** to request a label under a verified zone, such as `crm` or `crm.finance`, up to the depth the zone allows. Reserved labels (`www`, `api`, `mail`, underscore names and similar) are refused.

## Approval, publishing and revocation

The request waits for a technical owner unless the zone uses automatic approval, which also lets the builder publish their own record. Approval resolves the target from the app's latest published endpoint for the policy environment (the CloudFront hostname or Cloud Run gateway host), or the reviewer enters one. Registrar zones publish the CNAME immediately; manual zones show the record to add by hand. **Check DNS** reports live only when the name resolves to the target. Revocation removes the published record first; zones cannot be archived while hostnames are registered under them.

## HTTPS on the company name (AWS)

For apps on an AWS setup, publishing the record also starts edge TLS inside the company's own account:

1. **Certificate.** Diakrin asks AWS Certificate Manager in the company account for a certificate for the exact hostname (for example `crm.apps.example.com`), tagged into the setup like every other Diakrin resource. The private key never leaves the account. Registrar zones get the ACM validation CNAME written through the stored credential; manual zones show the record to add by hand. **Check certificate** re-reads the status.
2. **Edge binding.** Once the certificate is issued, the hostname shows *Certificate issued · deploy pending*. The next deployment of the app adds the name and certificate to the app's own CloudFront distribution through the usual reviewed CloudFormation change; nothing is changed behind the deployment's back. When the deployment is observed, the hostname shows *HTTPS live at the edge* and app sign-in accepts the company name.
3. **Detach and revoke.** A name that is served at the edge cannot be revoked directly. **Detach from edge** marks it for removal; the next deployment drops the alias; once that is observed, **Revoke** removes the DNS record. The record is therefore never deleted while the distribution still answers for the name.

One company name per app at a time, for Production apps. Preview apps use Preview links instead.

> [!SAAS]
> Preview links use a Diakrin-managed domain. Self-hosted installations have no Diakrin-managed preview domain; previews are served through your installation's own ingress.

## What this does not cover

On Google Cloud, the hostname resolves to the app's gateway, but Diakrin does not yet set up HTTPS on the name, so the **Company hostname** card reports DNS only.
