> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Domains

> Set up custom domains for EngageFabric enterprise accounts. Configure DNS, SSL certificates, and branded API endpoints for your organization.

<Info>
  Custom domains are available on **Professional** and **Enterprise** plans. [Upgrade your plan](/pricing) to enable this feature.
</Info>

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

```bash theme={null}
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:**

```json theme={null}
{
  "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:

<Steps>
  <Step title="Add TXT Record">
    This verifies you own the domain:

    * **Type**: TXT
    * **Name**: `_engagefabric-verify.api.yourgame.com`
    * **Value**: `{verificationToken from response}`
  </Step>

  <Step title="Add CNAME Record">
    This routes traffic to EngageFabric:

    * **Type**: CNAME
    * **Name**: `api.yourgame.com`
    * **Value**: `custom.engagefabric.com`
  </Step>

  <Step title="Wait for Propagation">
    DNS changes can take up to 48 hours to propagate, though most complete within 15 minutes.
  </Step>
</Steps>

<Note>
  If you're using Cloudflare, disable the proxy (orange cloud) for the CNAME record to allow SSL certificate provisioning.
</Note>

### Step 3: Verify the Domain

Once DNS records are configured, verify the domain:

```bash theme={null}
curl -X POST https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response (Success):**

```json theme={null}
{
  "verified": true
}
```

**Response (Failure):**

```json theme={null}
{
  "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:

```bash theme={null}
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:

<CodeGroup>
  ```javascript JavaScript SDK theme={null}
  import { EngageFabric } from '@engagefabricsdk/sdk';

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

  ```typescript React SDK theme={null}
  import { EngageFabricProvider } from '@engagefabricsdk/react';

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

## Managing Custom Domains

### List All Domains

```bash theme={null}
curl -X GET https://api.engagefabric.com/api/v1/enterprise/domains \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Get Domain Details

```bash theme={null}
curl -X GET https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Remove a Domain

```bash theme={null}
curl -X DELETE https://api.engagefabric.com/api/v1/enterprise/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

<Warning>
  Removing a domain immediately stops serving traffic from that domain. Update your SDK configuration before removing domains.
</Warning>

## 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:

```json theme={null}
{
  "sslIssuedAt": "2025-12-31T12:00:00.000Z",
  "sslExpiresAt": "2026-03-31T12:00:00.000Z"
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="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:**

    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
  </Accordion>

  <Accordion title="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:**

    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)
  </Accordion>

  <Accordion title="Domain works but shows certificate error">
    **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
  </Accordion>
</AccordionGroup>

## 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           |

***

## Related

<CardGroup cols={2}>
  <Card title="Enterprise SSO" icon="key" href="/guides/enterprise-sso">
    Configure single sign-on for your organization
  </Card>

  <Card title="SDK Overview" icon="code" href="/sdks/overview">
    Learn how to configure the SDK with your custom domain
  </Card>
</CardGroup>