Search documentation

Search documentation pages and headings.

Skip to content

Administration · How-to guide

Register domains

Register trusted auth and root hostnames, provision DNS, and automate domain lifecycle through the server API.

Domains bind a public authentication hostname to the root application hostname that may initiate callbacks. They can also select project or organization branding.

Admin registration#

Open Admin > Domains > Create domain and enter:

  • Auth hostname: the hostname users visit, for example auth.institute.example.com
  • Root hostname: the trusted application hostname, for example institute.example.com
  • Project: optional project branding and enabled auth methods
  • Organization: optional organization branding
  • Managed: whether Krakstack Auth should provision a Cloudflare custom hostname

Use hostnames only. Do not include https://, paths, ports, query strings, or trailing slashes.

Server API registration#

Trusted provisioning services can automate domain lifecycle with a service API key:

http
POST /api/domainsx-api-key: SERVICE_API_KEYcontent-type: application/json
{  "hostname": "auth.institute.example.com",  "rootHostname": "institute.example.com",  "projectId": "project_id",  "organizationId": "organization_id",  "managed": true}

The trusted server API also supports lookup by ID or hostname, DNS record retrieval, and deletion. Updates are available only through the cookie-authenticated administrative API. Keep the service key in server-side secret storage and restrict which systems can provision domains.

DNS and activation#

For managed domains, retrieve the requested records and publish them at the DNS provider. Cloudflare status is refreshed when domains are listed or DNS records are requested. Requests only resolve domain context after a unique registered domain is active.

For unmanaged domains, route the hostname to the auth deployment yourself and ensure your TLS proxy preserves the original host and protocol correctly.

Deletion#

Deleting the final domain record for a managed Cloudflare hostname also removes that hostname. A hostname shared by another domain record is retained. Remove application references and OAuth callbacks first, then delete DNS records after traffic has drained.