Skip to main content
Custom domains are available on Professional and Enterprise plans. Upgrade your plan to enable this feature.
Custom domains allow you to serve the EngageFabric API from your own domain (e.g., api.yourgame.com), providing a seamless white-label experience for your users.

​
Domain Types

You can configure custom domains for different purposes:
TypeDescriptionExample
APICustom API endpointapi.yourgame.com
ADMINCustom admin consoleadmin.yourgame.com
DOCSCustom documentationdocs.yourgame.com

​
Adding a Custom Domain

​
Step 1: Add the Domain

curl -X POST https://api.engagefabric.com/api/v1/enterprise/domains \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "api.yourgame.com",
    "domainType": "API"
  }'
Response: 
{
  "domain": {
    "id": "dom_abc123",
    "domain": "api.yourgame.com",
    "domainType": "API",
    "verified": false,
    "verificationToken": "ef8a3b...",
    "verificationMethod": "TXT",
    "sslStatus": "PENDING",
    "isActive": false,
    "createdAt": "2025-12-31T12:00:00.000Z"
  },
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_engagefabric-verify.api.yourgame.com",
      "value": "ef8a3b..."
    },
    {
      "type": "CNAME",
      "name": "api.yourgame.com",
      "value": "custom.engagefabric.com"
    }
  ]
}

​
Step 2: Configure DNS Records

Add the provided DNS records to your domain’s DNS settings:
1

Add TXT Record

This verifies you own the domain:
  • Type: TXT
  • Name: _engagefabric-verify.api.yourgame.com
  • Value: {verificationToken from response}
2

Add CNAME Record

This routes traffic to EngageFabric:
  • Type: CNAME
  • Name: api.yourgame.com
  • Value: custom.engagefabric.com
3

Wait for Propagation

DNS changes can take up to 48 hours to propagate, though most complete within 15 minutes.
If you’re using Cloudflare, disable the proxy (orange cloud) for the CNAME record to allow SSL certificate provisioning.

​
Step 3: Verify the Domain

Once DNS records are configured, verify the domain: 
curl -X POST https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response (Success): 
{
  "verified": true
}
Response (Failure): 
{
  "verified": false,
  "error": "DNS TXT record not found. Please ensure you have added the correct DNS record."
}

​
Step 4: SSL Certificate Provisioning

After verification, we automatically provision an SSL certificate for your domain:
StatusDescription
PENDINGWaiting for domain verification
ISSUINGCertificate is being provisioned
ACTIVECertificate active, domain ready to use
FAILEDCertificate provisioning failed
Check the status: 
curl -X GET https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
The domain becomes active once sslStatus is ACTIVE and isActive is true.

​
Using Your Custom Domain

Once active, configure your SDK to use your custom domain: 
import { EngageFabric } from '@engagefabricsdk/sdk';

const client = new EngageFabric({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.yourgame.com/api'
});

​
Managing Custom Domains

​
List All Domains

curl -X GET https://api.engagefabric.com/api/v1/enterprise/domains \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Get Domain Details

curl -X GET https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Remove a Domain

curl -X DELETE https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Removing a domain immediately stops serving traffic from that domain. Update your SDK configuration before removing domains.

​
DNS Record Reference

​
TXT Record (Verification)

FieldValue
TypeTXT
Name_engagefabric-verify.{your-domain}
ValueYour verification token
TTL300 (5 minutes) or default

​
CNAME Record (Traffic Routing)

FieldValue
TypeCNAME
Name{your-domain}
Valuecustom.engagefabric.com
TTL300 (5 minutes) or default

​
SSL Certificate Details

We use Let’s Encrypt to provision SSL certificates:
  • Certificate Authority: Let’s Encrypt
  • Validity: 90 days (auto-renewed)
  • Protocol: TLS 1.2 and 1.3
  • Cipher Suites: Modern, secure defaults
You can check certificate expiry in the domain details response: 
{
  "sslIssuedAt": "2025-12-31T12:00:00.000Z",
  "sslExpiresAt": "2026-03-31T12:00:00.000Z"
}

​
Troubleshooting

Common causes:
  • DNS records haven’t propagated yet (wait up to 48 hours)
  • TXT record has the wrong name or value
  • Domain has conflicting DNS records
Debug steps:
  1. Use dig TXT _engagefabric-verify.yourdomain.com to check the record
  2. Verify the token matches exactly (no trailing spaces)
  3. Try verification again after confirming DNS
Common causes:
  • CNAME record not configured correctly
  • Cloudflare proxy enabled (disable orange cloud)
  • Domain has CAA records blocking Let’s Encrypt
Debug steps:
  1. Check CNAME resolves: dig CNAME yourdomain.com
  2. Check CAA records: dig CAA yourdomain.com
  3. If using Cloudflare, set DNS-only mode (gray cloud)
Common causes:
  • Certificate still provisioning (check sslStatus)
  • Certificate expired (check sslExpiresAt)
  • Browser caching old certificate
Debug steps:
  1. Check domain status in API
  2. Clear browser cache and try incognito mode
  3. Wait 5 minutes for certificate propagation

​
API Reference

MethodEndpointDescription
GET/v1/enterprise/domainsList all custom domains
POST/v1/enterprise/domainsAdd a custom domain
GET/v1/enterprise/domains/:idGet domain details
POST/v1/enterprise/domains/:id/verifyVerify DNS records
DELETE/v1/enterprise/domains/:idRemove domain

Enterprise SSO

Configure single sign-on for your organization

SDK Overview

Learn how to configure the SDK with your custom domain