Search documentation

Search documentation pages and headings.

Skip to content

Customization · How-to guide

Custom domains

Connect and verify a branded domain for your learning portal.

A custom domain serves your organization's Kokobi portal from a hostname you control, such as learn.example.com. It also provides the tenant context used by branded pages, authentication, links, and email configuration.

Each organization can have one custom domain. A hostname cannot be assigned to more than one organization.

Before You Start#

You need:

  • Permission to manage the organization.
  • Access to the DNS provider for the hostname.
  • A valid subdomain such as learn.example.com.

Kokobi currently requires a dedicated subdomain. Root domains such as example.com are not accepted.

Add a Domain#

  1. Open Admin > Domains.
  2. Enter the complete hostname without https:// or a path.
  3. Create the domain.
  4. Kokobi displays the DNS records required for routing, authentication, and email.
  5. Add those records at your DNS provider exactly as shown.
  6. Return to the domain page and refresh until the domain becomes ACTIVE.

The domain remains PENDING while the routing hostname is not verified. Email DNS records are verified separately and do not block portal activation.

DNS Records#

Always copy the names, values, and priorities from the Kokobi domain table. The exact values are generated for your hostname.

You may see:

  • A required CNAME that routes the portal hostname to Kokobi.
  • DKIM CNAME records that verify email signing.
  • An MX record and SPF TXT record for the email return path.
  • An optional DMARC TXT record.

DNS providers differ: some expect a record name relative to the root domain, while others expect the complete hostname. Use the names Kokobi displays and check your provider's convention before adding the root domain suffix.

Do not copy quotation marks into a TXT value unless your DNS provider requires them. Do not proxy or flatten the routing CNAME unless your provider's behavior is known to preserve custom-hostname verification.

Verification and Activation#

DNS changes can take time to propagate. Kokobi checks the routing hostname and email identity and shows a status for each row:

  • SUCCESS means the record has been verified.
  • MISSING or another pending status means verification is not complete.
  • OPTIONAL identifies a recommended record that does not block portal activation.

The domain becomes active when the routing hostname is active. TLS is provisioned for the hostname; no certificate upload is required in Kokobi.

Email verification may complete separately from portal activation. Keep all required DKIM, MX, and SPF records in place so branded notification delivery continues to work.

Test the Domain#

After activation:

  1. Open the hostname over HTTPS.
  2. Confirm the organization home page loads.
  3. Sign in and open both Admin and Learner areas.
  4. Test a course or collection join link generated for the domain.
  5. Send a notification and confirm expected email branding and delivery.
  6. Review white-label customizations in light and dark modes.

Troubleshooting#

The CNAME stays pending#

  • Confirm the record name is attached to the intended hostname.
  • Confirm the value matches the domain table exactly.
  • Disable DNS proxying temporarily if it hides the CNAME target.
  • Remove conflicting A, AAAA, or CNAME records for the same name.
  • Allow time for the record's TTL to expire, then refresh the domain page.

Email records stay pending#

  • Check every DKIM record; there can be multiple generated tokens.
  • Confirm the MX priority matches the value shown in Kokobi.
  • Confirm the SPF TXT record is attached to the displayed email subdomain.
  • Check for provider-added quotes or an accidental duplicate domain suffix.

Delete or Replace a Domain#

Deleting a domain removes its Kokobi routing and email configuration. Previously issued invite, share, and completion links that use the hostname will stop working.

To replace a domain, record where the old hostname is used, delete it from Kokobi, add the new hostname, publish the new DNS records, and update external links. Keep redirects at your own infrastructure when possible.