Reference → Domains — Reference

Domains — Reference

The Domains surface is the custom-hostname plane for every SGEN site. It owns the catalogue of domains a site answers on, the DNS verification flow that confirms an operator controls a domain before it is attached, the SSL provisioning record that binds an HTTPS certificate to each domain, the redirect rules that route requests between hostnames, and the multi-domain configuration that lets a single site serve more than one public hostname.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a custom-domain integration. Customer-facing setup walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Domains live under the Settings → Domains module in SG-Admin. The module renders four primary views — the domain list, the add-domain wizard, the DNS record viewer, and the redirect editor — and exposes write operations for domain attach, verification trigger, primary toggle, redirect edit, and domain detach.

The module is paired by convention with the SSL provisioning service and the platform's edge routing layer. Engineers reading the SG-Admin source will see the read half (domain enumeration, verification status, certificate status) split from the write half (domain CRUD, verification retries, primary toggle, redirect rules); the reference below describes the combined surface as it appears to a calling integration.

A second surface — redirect rules — lives adjacent under the same module. Redirect rules let an operator declare hostname-to-hostname or path-level redirects, which the edge router applies before serving a request. Rules are evaluated in order, first match wins.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Settings → Domains
URL prefix: /sg-admin/domains/
View templates: application/views/Admin/Domains/

The module surface is scoped to hostname binding and routing. The platform's default subdomain (under sgen.com) is provisioned automatically at site creation and listed here as a non-removable entry; this page covers the catalogue of additional hostnames that an operator attaches on top of the default.

┌────────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings → Domains [+ Add domain]│├────────────────────────────────────────────────────────────────────────┤│ Hostname Primary SSL Verification ││ ────────────────────── ───────── ─────────── ──────────────────── ││ site-name.sgen.com — Issued Auto (default) ││ www.acme-co.com ✓ Issued Verified 2 days ago ││ acme-co.com — Issued Verified 2 days ago ││ shop.acme-co.com — Pending Awaiting CNAME ││ legacy.acme-co.com — Issued Redirect → primary ││ ││ [⋯ Verify] [⋯ Set primary] [⋯ Redirect rules] [⋯ Detach] │└────────────────────────────────────────────────────────────────────────┘

Actions

The Domains surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List domains

Returns the domains attached to the current site, in attachment order. Each row carries the hostname, the primary flag (exactly one domain may be primary at a time), the SSL certificate status, and the verification status. The default subdomain under sgen.com is always present and cannot be detached.

Attach domain (add-domain wizard)

Opens a multi-step wizard. Step one captures the hostname. Step two displays the DNS records the operator must publish at the domain registrar — either an A record pointing at the platform's edge IP or a CNAME pointing at the site's default subdomain. Step three triggers verification; the surface polls the domain's authoritative nameservers and confirms the records resolve to the expected values. On success, the domain is attached and queued for SSL provisioning.

Trigger verification

For a domain in pending verification state, this action retriggers the DNS check. The surface re-queries the domain's authoritative nameservers, compares the resolved records to the expected values, and either advances the domain to verified or returns a structured rejection naming the record that failed to resolve.

Provision SSL

For a domain in verified state, the platform's SSL provisioning service requests a certificate from the configured certificate authority. The action returns immediately with a pending certificate status; the surface polls the provisioning service until issuance, renewal failure, or rate-limit error. Certificates renew automatically; the surface exposes a renewal log for audit.

Set primary

Marks one attached domain as the primary. The primary domain is the canonical hostname returned by any internal link generator, the redirect target for non-primary hostnames that do not have an explicit redirect rule, and the host included in transactional email links and structured-data emit. Exactly one domain may be primary; setting a new primary unsets the previous one.

Edit redirect rule

Opens the redirect editor. A rule binds a source pattern — hostname-only or hostname-plus-path — to a destination — hostname, hostname-plus-path, or external URL — and a redirect type (301 permanent or 302 temporary). Rules are stored with a display order; the edge router evaluates them in order on each incoming request, first match wins.

Detach domain

Removes a domain from the site. The surface prompts for confirmation, lists the redirect rules referencing the domain (which become orphaned), and on confirm removes the domain and revokes its SSL certificate. The default subdomain cannot be detached.

Renew SSL

Manually triggers an SSL renewal for a domain whose certificate is approaching expiry or whose automatic renewal failed. Returns a structured response: success, rate-limited, or DNS-resolution-failure (the certificate authority requires the domain to still resolve to the platform during renewal).

Data model

A domain record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`id`	integer	Primary key. Stable across edits.
`hostname`	string	The fully qualified hostname. Unique across the platform.
`site_id`	integer	Foreign key to the parent site.
`is_primary`	boolean	True for exactly one domain per site.
`verification_method`	enum	`cname`, `a-record`, or `auto` (default subdomain only).
`verification_target`	string	The expected record value the operator publishes.
`verification_status`	enum	`pending`, `verified`, or `failed`.
`verified_at`	timestamp	Set on transition to `verified`.
`ssl_status`	enum	`none`, `pending`, `issued`, `renewal-failed`.
`ssl_issued_at`	timestamp	Set on transition to `issued`.
`ssl_expires_at`	timestamp	Carried from the issued certificate.
`created_at`	timestamp	Set on attach, immutable.
`updated_at`	timestamp	Touched on any edit.

A redirect rule carries:

Field	Type	Notes
`id`	integer	Primary key.
`site_id`	integer	Foreign key to the parent site.
`source_hostname`	string	The hostname the rule matches on.
`source_path_pattern`	string	Optional. A path or wildcard pattern; empty means hostname-only.
`destination_url`	string	The redirect target — internal or external.
`redirect_type`	enum	`301` (permanent) or `302` (temporary).
`display_order`	integer	Evaluation order — lower wins.
`status`	enum	`active` or `inactive`.
`created_at`	timestamp	Set on create, immutable.
`updated_at`	timestamp	Touched on any edit.

SITE├── default subdomain (auto, non-removable)└── attached domains└── DOMAIN├── hostname fully qualified├── is_primary exactly one per site├── verification_method cname | a-record | auto├── verification_status pending | verified | failed├── ssl_status none | pending | issued | renewal-failed└── ssl_expires_at timestamp↓ associated withREDIRECT RULE (zero or more per site)├── source_hostname hostname the rule matches├── source_path_pattern optional path matcher├── destination_url redirect target├── redirect_type 301 | 302└── display_order evaluation priority

Verification lifecycle. A domain transitions pending → verified on successful DNS check, or pending → failed after the configured retry budget is exhausted. From failed, the operator may retrigger verification; from verified, periodic background checks may detect that the records have been removed at the registrar, and the surface emits a warning (the domain is not auto-detached, but the operator is notified).

SSL lifecycle. An issued certificate carries an ssl_expires_at timestamp. The provisioning service schedules renewal at thirty days before expiry. A failed renewal transitions ssl_status to renewal-failed; the certificate remains valid until expiry, and the operator may manually retry through the renew action.

Permissions

Access to the Domains surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Domains surface.

Layer 2 — per-action capability. Within SG-Admin, each Domains action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:

Capability	Administrator	Editor	Viewer
List domains	✔	✔	✔
Attach domain	✔	—	—
Trigger verification	✔	—	—
Provision SSL	✔	—	—
Renew SSL	✔	—	—
Set primary	✔	—	—
Edit redirect rule	✔	—	—
Detach domain	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Self-protection rules. The default subdomain cannot be detached, cannot be unset as a verification anchor, and is always available as a fallback hostname even if every attached custom domain is in a failed state. The surface returns a structured rejection on any attempt to detach the default subdomain.

Audit. Every write — domain attach, verification trigger, SSL provision, SSL renew, primary toggle, redirect rule edit, domain detach — emits an Activity Log entry. The log records the acting operator, the target hostname, and the change shape. SSL events are tagged for compliance review. Activity Log retention is governed by the site's general settings.

ATTACH DOMAIN│▼┌──────────────────────────────┐│ Operator publishes DNS at ││ registrar (CNAME or A) │└──────────────┬───────────────┘▼Trigger verification│┌───────┴───────┐│ │▼ ▼verified failed│ ││ └→ operator retries (budgeted)▼Provision SSL│▼Issued ──────────────────────┐│ ││ (background) │▼ │30 days before expiry ││ │▼ │Auto-renew ││ │└──→ renewal-failed → operator manually retries▼[renewed]

Related references

Settings — Reference. Owns the site's primary contact email (used by the certificate authority for issuance notifications), the role capability map that gates this surface, and the redirect retention rule.
SEO — Reference. Canonical-URL emit, sitemap-host emit, and structured-data hostname references all read from the primary domain set here.
Email — Reference. Transactional email links and unsubscribe URLs are built against the primary domain.
Forms — Reference. Form action URLs and webhook delivery callbacks reference the primary domain.
Custom Codes — Reference. Custom code blocks scoped to a hostname read against the domain catalogue here.
Activity Log — Reference. Domain-related events, including SSL issuance and renewal failures, surface in the activity log feed.

For the corresponding customer-facing walkthrough — attaching a domain, publishing DNS records, configuring redirects — see the Domains section of the customer docs at /docs/domains.

On this page

Guides

Reference

Changelog

Roadmap