Custom Domains

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:

Type	Description	Example
`API`	Custom API endpoint	`api.yourgame.com`
`ADMIN`	Custom admin console	`admin.yourgame.com`
`DOCS`	Custom documentation	`docs.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:

Add TXT Record

This verifies you own the domain:

Type: TXT
Name: _engagefabric-verify.api.yourgame.com
Value: {verificationToken from response}

Add CNAME Record

This routes traffic to EngageFabric:

Type: CNAME
Name: api.yourgame.com
Value: custom.engagefabric.com

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:

Status	Description
`PENDING`	Waiting for domain verification
`ISSUING`	Certificate is being provisioned
`ACTIVE`	Certificate active, domain ready to use
`FAILED`	Certificate 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'
});

import { EngageFabricProvider } from '@engagefabricsdk/react';

function App() {
  return (
    <EngageFabricProvider
      apiKey="YOUR_API_KEY"
      baseUrl="https://api.yourgame.com/api"
    >
      {/* Your app */}
    </EngageFabricProvider>
  );
}

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)

Field	Value
Type	TXT
Name	`_engagefabric-verify.{your-domain}`
Value	Your verification token
TTL	300 (5 minutes) or default

CNAME Record (Traffic Routing)

Field	Value
Type	CNAME
Name	`{your-domain}`
Value	`custom.engagefabric.com`
TTL	300 (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

Domain verification fails

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:

Use dig TXT _engagefabric-verify.yourdomain.com to check the record
Verify the token matches exactly (no trailing spaces)
Try verification again after confirming DNS

SSL certificate fails to provision

Common causes:

CNAME record not configured correctly
Cloudflare proxy enabled (disable orange cloud)
Domain has CAA records blocking Let’s Encrypt

Debug steps:

Check CNAME resolves: dig CNAME yourdomain.com
Check CAA records: dig CAA yourdomain.com
If using Cloudflare, set DNS-only mode (gray cloud)

Domain works but shows certificate error

Common causes:

Certificate still provisioning (check sslStatus)
Certificate expired (check sslExpiresAt)
Browser caching old certificate

Debug steps:

Check domain status in API
Clear browser cache and try incognito mode
Wait 5 minutes for certificate propagation

API Reference

Method	Endpoint	Description
GET	`/v1/enterprise/domains`	List all custom domains
POST	`/v1/enterprise/domains`	Add a custom domain
GET	`/v1/enterprise/domains/:id`	Get domain details
POST	`/v1/enterprise/domains/:id/verify`	Verify DNS records
DELETE	`/v1/enterprise/domains/:id`	Remove domain

Enterprise SSO

Configure single sign-on for your organization

SDK Overview

Learn how to configure the SDK with your custom domain

Getting Started

Guides

Core Concepts

API Reference

Endpoints

SDKs

Resources

Domain Types

Adding a Custom Domain

Step 1: Add the Domain

Step 2: Configure DNS Records

Step 3: Verify the Domain

Step 4: SSL Certificate Provisioning

Using Your Custom Domain

Managing Custom Domains

List All Domains

Get Domain Details

Remove a Domain

DNS Record Reference

TXT Record (Verification)

CNAME Record (Traffic Routing)

SSL Certificate Details

Troubleshooting

API Reference

Enterprise SSO

SDK Overview

​Domain Types

​Adding a Custom Domain

​Step 1: Add the Domain

​Step 2: Configure DNS Records

​Step 3: Verify the Domain

​Step 4: SSL Certificate Provisioning

​Using Your Custom Domain

​Managing Custom Domains

​List All Domains

​Get Domain Details

​Remove a Domain

​DNS Record Reference

​TXT Record (Verification)

​CNAME Record (Traffic Routing)

​SSL Certificate Details

​Troubleshooting

​API Reference

​Related

Enterprise SSO

SDK Overview

Domain Types

Adding a Custom Domain

Step 1: Add the Domain

Step 2: Configure DNS Records

Step 3: Verify the Domain

Step 4: SSL Certificate Provisioning

Using Your Custom Domain

Managing Custom Domains

List All Domains

Get Domain Details

Remove a Domain

DNS Record Reference

TXT Record (Verification)

CNAME Record (Traffic Routing)

SSL Certificate Details

Troubleshooting

API Reference

Related