Custom Domains

Add custom domains with automatic SSL certificates

Overview

Map custom domains to your Scalix Cloud services with automatic SSL/TLS certificate provisioning. Custom domains are free on all plans with automatic SSL via Let's Encrypt.

Plan	Domains Included
Free	1
Chat Plus	1
Starter	3
Pro	10
Team+	Unlimited

CLI

bash

# Add a domain
scalix-cloud domain add app.example.com
 
# List domains
scalix-cloud domain list
 
# Remove a domain
scalix-cloud domain rm app.example.com

REST API

Add a Domain

bash

curl -X POST https://api.scalix.world/v1/domains \
  -H "Authorization: Bearer $SCALIX_API_KEY" \
  -d '{"domain": "app.example.com"}'

The response includes the domain record (note the id — you need it for verification and SSL) plus step-by-step DNS instructions:

json

{
  "domain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "app.example.com",
    "status": "pending",
    "verification_token": "scalix-verify-...",
    "ssl_status": "none",
    "cname_target": "cname.scalix.world"
  },
  "instructions": {
    "step_1": "Add a CNAME record for 'app.example.com' pointing to 'cname.scalix.world'",
    "step_2": "Add a TXT record '_scalix-verify.app.example.com' with the verification token",
    "step_3": "Call POST /v1/domains/{id}/verify to confirm DNS setup",
    "step_4": "Call POST /v1/domains/{id}/ssl to provision SSL certificate"
  }
}

Verify Domain

After adding both DNS records, verify using the domain ID from the create response:

bash

curl -X POST https://api.scalix.world/v1/domains/{id}/verify \
  -H "Authorization: Bearer $SCALIX_API_KEY"

SSL Certificates

SSL is automatic. Once a domain is verified, request a certificate with POST /v1/domains/{id}/ssl:

bash

curl -X POST https://api.scalix.world/v1/domains/{id}/ssl \
  -H "Authorization: Bearer $SCALIX_API_KEY"

Scalix orders a certificate from Let's Encrypt using an HTTP-01 challenge — once your domain's CNAME points at Scalix, there are no extra DNS records for you to add. Scalix installs the certificate and renews it automatically ~30 days before expiry. Issuance usually completes within a few minutes — track progress via the domain's ssl_status field (provisioning → active).

DNS Configuration

Two records are required — a CNAME for routing and a TXT for ownership verification:

plaintext

app.example.com                  CNAME  cname.scalix.world
_scalix-verify.app.example.com   TXT    scalix-verify-<token>

For apex domains (e.g., example.com), use an A record or ALIAS record depending on your DNS provider.