White-Label Setup

Intermediate - 20 minutes

Prerequisites: Domain ownership, DNS access, Business plan or higher

Customize BoardAPI appearance to match your brand with custom domains and white-label options.

Overview

White-labeling allows you to:

Use your own domain instead of app.boardapi.io
Remove "Powered by BoardAPI" branding from the interface
Seamless integration with automatic SSL certificates
Complete transparency for your end users

Your boards will be available at https://your-domain.com/board/{uuid} instead of https://app.boardapi.io/board/{uuid}.

Requirements

To use white-label features, you need:

Business plan or higher (see Pricing)
Custom domain or subdomain (e.g., boards.yourcompany.com)
DNS management access for your domain
Organization account with BoardAPI

Quick Start

Step 1: Choose Your Domain

Decide which domain or subdomain you want to use:

✅ boards.yourcompany.com (recommended)
✅ whiteboard.yoursite.com
✅ wb.yourdomain.com
❌ yourcompany.com (root domains not supported)

Step 2: Add Domain in Settings

Via Web Interface:

Log in to app.boardapi.io
Navigate to Settings → White-Label
Click "Add Custom Domain"
Enter your domain (e.g., boards.yourcompany.com)
Click "Add Domain"

Via API:

bash

curl -X POST https://app.boardapi.io/api/v1/organizations/{orgId}/custom-domains \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "boards.yourcompany.com"
  }'

Response:

json

{
  "id": "domain-uuid",
  "domain": "boards.yourcompany.com",
  "status": "pending",
  "dns_instructions": {
    "type": "CNAME",
    "name": "boards.yourcompany.com",
    "value": "app.boardapi.io",
    "ttl": 3600
  },
  "next_steps": "Add the CNAME record to your DNS provider and verify."
}

Step 3: Configure DNS

Add a CNAME record in your DNS provider pointing to app.boardapi.io:

Type	Name	Value	TTL
CNAME	boards.yourcompany.com	app.boardapi.io	3600

Popular DNS Providers

Cloudflare:

Go to DNS → Records
Click "Add Record"
Type: CNAME
Name: boards (subdomain part)
Target: app.boardapi.io
⚠️ Important: Set Proxy status to "DNS only" (gray cloud)
Click "Save"

GoDaddy:

Go to DNS Management
Click "Add" under Records
Type: CNAME
Host: boards
Points to: app.boardapi.io
TTL: 1 Hour
Click "Save"

Namecheap:

Go to Advanced DNS
Click "Add New Record"
Type: CNAME Record
Host: boards
Value: app.boardapi.io
TTL: Automatic
Click "Save"

Step 4: Verify Domain

After configuring DNS (wait 5-30 minutes for propagation):

Via Web Interface:

Go to Settings → White-Label
Find your domain in the list
Click "Verify Domain"
Wait for status to change to "verified"

Via API:

bash

curl -X POST https://app.boardapi.io/api/v1/organizations/{orgId}/custom-domains/{domainId}/verify \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Successful Response:

json

{
  "id": "domain-uuid",
  "domain": "boards.yourcompany.com",
  "status": "verified",
  "ssl_status": "pending",
  "verified_at": "2025-11-28T10:30:00.000Z",
  "message": "DNS verified! SSL certificate is being issued (2-10 minutes)."
}

Step 5: SSL Certificate (Automatic)

After DNS verification, an SSL certificate is automatically issued via Let's Encrypt:

⏳ Process takes 2-10 minutes
✅ Status changes to "active" when ready
🔄 Certificates auto-renew every 90 days

Check Status:

bash

curl https://app.boardapi.io/api/v1/organizations/{orgId}/custom-domains/{domainId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

When Ready:

json

{
  "id": "domain-uuid",
  "domain": "boards.yourcompany.com",
  "status": "active",
  "ssl_status": "issued",
  "ssl_issued_at": "2025-11-28T10:35:00.000Z"
}

Step 6: Start Using Your Domain

Once active, all new boards will automatically use your custom domain:

Before:

https://app.boardapi.io/board/abc-123?token=xyz

After:

https://boards.yourcompany.com/board/abc-123?token=xyz

✅ Old links continue to work ✅ New boards use your custom domain ✅ API responses include your domain in access links

Customization Options

Branding Removal

With Professional plan or higher, the "Powered by BoardAPI" footer is automatically removed.

Domain Configuration

You can configure multiple aspects of your white-label setup:

Organization Branding:

bash

curl -X PATCH https://app.boardapi.io/api/v1/organizations/{orgId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "branding": {
        "companyName": "Your Company",
        "logo": "https://your-cdn.com/logo.svg"
      }
    }
  }'

Custom Colors (Future Feature):

Theme customization will be available in a future update:

javascript

// Coming soon
{
  "branding": {
    "primaryColor": "#3B82F6",
    "accentColor": "#10B981",
    "fontFamily": "Inter, sans-serif"
  }
}

API Reference

List Custom Domains

http

GET /api/v1/organizations/{orgId}/custom-domains
Authorization: Bearer {jwt_token}

Response:

json

{
  "domains": [
    {
      "id": "uuid",
      "domain": "boards.yourcompany.com",
      "status": "active",
      "ssl_status": "issued",
      "is_default": true,
      "created_at": "2025-11-23T...",
      "verified_at": "2025-11-23T..."
    }
  ]
}

Add Custom Domain

http

POST /api/v1/organizations/{orgId}/custom-domains
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "domain": "boards.yourcompany.com"
}

Verify Domain

http

POST /api/v1/organizations/{orgId}/custom-domains/{domainId}/verify
Authorization: Bearer {jwt_token}

Remove Domain

http

DELETE /api/v1/organizations/{orgId}/custom-domains/{domainId}
Authorization: Bearer {jwt_token}

Effect:

Domain removed from configuration
Access links revert to app.boardapi.io
Existing boards continue to work
You can safely remove the DNS CNAME record

Domain Statuses

Status	Description	Action Required
`pending`	Domain added, awaiting DNS setup	Configure CNAME record
`verified`	DNS configured, SSL being issued	Wait 2-10 minutes
`active`	Domain fully operational	✅ Ready to use
`failed`	Verification or SSL issuance failed	Check DNS settings

Verification & Testing

Check DNS Propagation

macOS/Linux:

bash

dig boards.yourcompany.com CNAME

# Expected output:
# boards.yourcompany.com. 300 IN CNAME app.boardapi.io.

Windows:

cmd

nslookup -type=CNAME boards.yourcompany.com

# Expected output:
# boards.yourcompany.com canonical name = app.boardapi.io

Online Tools:

Test SSL Certificate

bash

curl -I https://boards.yourcompany.com

# Expected: HTTP/2 200 (no SSL errors)

Verify Board Access

Create a test board and check the access link:

bash

curl -X POST https://app.boardapi.io/api/v1/boards \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Board"}'

Access links should use your custom domain:

json

{
  "board": {...},
  "access_links": {
    "host": "https://boards.yourcompany.com/board/abc123?token=...",
    "guest": "https://boards.yourcompany.com/board/abc123?token=..."
  }
}

Troubleshooting

DNS Not Verifying

Symptoms:

Verification fails with DNS error
dig command returns no results

Solutions:

Check CNAME record exists:
bash
```
dig boards.yourcompany.com CNAME
```
Wait for DNS propagation (can take 5 minutes to 24 hours)
Verify correct value:
- Target should be: app.boardapi.io
- NOT your IP address
- NOT other domains
Check for conflicts:
- Remove A records for the same subdomain
- Ensure only one CNAME record exists

SSL Certificate Not Issuing

Symptoms:

Status stuck on verified
SSL status shows pending for >10 minutes

Common Causes:

Cloudflare Proxy Enabled:

Go to Cloudflare DNS settings
Click the orange cloud next to your CNAME record
Change to gray cloud (DNS only)
Wait 5 minutes and try again

Port 80 Blocked:

Ensure your firewall allows HTTP traffic
Let's Encrypt uses HTTP challenge for verification

Existing SSL Certificate:

Remove any existing SSL certificates for this domain
Let BoardAPI manage SSL automatically

CORS Errors

Symptoms:

Access to XMLHttpRequest blocked by CORS policy

Solution: This should be handled automatically. If you see CORS errors:

Check domain is verified and active
Wait 2-3 minutes after verification
Clear browser cache
Contact support if persists

Domain Shows Error Page

Symptoms:

Visiting your domain shows Nginx error
502 Bad Gateway or 404 Not Found

Solutions:

Check domain status:
- Must be active in settings
- SSL must be issued
Wait for full propagation:
- DNS changes take time
- Try from different network/device

Clear DNS cache:

bash

# macOS
sudo dscacheutil -flushcache

# Windows
ipconfig /flushdns

Limitations

What You Can Customize

✅ Domain name (e.g., boards.yourcompany.com) ✅ Remove "Powered by BoardAPI" branding ✅ Company name and logo ✅ SSL certificate (automatic)

What You Cannot Customize

❌ Core Excalidraw UI components ❌ API endpoints structure ❌ WebSocket behavior ❌ Internal routing logic

Technical Constraints

Root domains not supported: Use subdomains only (e.g., boards.example.com not example.com)
One domain per organization: Contact sales for multiple domains
SSL managed by platform: Cannot use your own SSL certificates
Shared infrastructure: All requests route through BoardAPI servers

Pricing Tiers

Feature	Starter	Professional	Business	Enterprise
Custom Domain	❌	❌	✅	✅
Branding Removal	❌	✅	✅	✅
SSL Certificate	—	—	Auto	Auto
Multiple Domains	—	—	1	Custom
Custom Logo	❌	❌	✅	✅

See full Pricing Details

Support

If you encounter issues with white-label setup:

Email: support@boardapi.io

Include in your request:

Your domain (e.g., boards.yourcompany.com)
Organization ID
Screenshot of DNS settings
Output of dig YOUR_DOMAIN CNAME command

Response Times:

Professional: 48 hours
Business: 24 hours
Enterprise: 4 hours (phone support available)

Setup Checklist

Use this checklist to ensure proper white-label configuration:

[ ] Business plan or higher activated
[ ] Domain or subdomain selected
[ ] Domain added in Settings → White-Label
[ ] CNAME record created in DNS (points to app.boardapi.io)
[ ] DNS propagation verified (dig command shows CNAME)
[ ] Domain verified in BoardAPI (status: verified)
[ ] SSL certificate issued (status: active)
[ ] HTTPS works (visit https://your-domain.com)
[ ] Test board created with custom domain link
[ ] WebSocket connection works (real-time updates)

Timeline Expectations

Typical setup time:

Step	Duration
Add domain in settings	1 minute
Configure DNS record	5-10 minutes
DNS propagation	5-30 minutes (can be up to 24h)
Domain verification	Instant once DNS propagates
SSL certificate issuance	2-10 minutes
Total	15-60 minutes (typical)

95% of domains are fully operational within 1 hour of DNS configuration.

Next Steps

After white-label setup:

Test thoroughly: Create test boards and verify all features work
Update documentation: Inform your users about the new domain
Migrate existing links: Old links continue to work, but you can update them
Monitor usage: Check analytics to ensure proper routing
Set up webhooks: Configure webhooks to use your custom domain (optional)

Last Updated: 2025-11-28 Applies to: Business and Enterprise plans

White-Label Setup ​

Overview ​

Requirements ​

Quick Start ​

Step 1: Choose Your Domain ​

Step 2: Add Domain in Settings ​

Step 3: Configure DNS ​

Popular DNS Providers ​

Step 4: Verify Domain ​

Step 5: SSL Certificate (Automatic) ​

Step 6: Start Using Your Domain ​

Customization Options ​

Branding Removal ​

Domain Configuration ​

API Reference ​

List Custom Domains ​

Add Custom Domain ​

Verify Domain ​

Remove Domain ​

Domain Statuses ​

Verification & Testing ​

Check DNS Propagation ​

Test SSL Certificate ​

Verify Board Access ​

Troubleshooting ​

DNS Not Verifying ​

SSL Certificate Not Issuing ​

CORS Errors ​

Domain Shows Error Page ​

Limitations ​

What You Can Customize ​

What You Cannot Customize ​

Technical Constraints ​

Pricing Tiers ​

Support ​

Setup Checklist ​

Timeline Expectations ​

Next Steps ​

Related Documentation ​

White-Label Setup

Overview

Requirements

Quick Start

Step 1: Choose Your Domain

Step 2: Add Domain in Settings

Step 3: Configure DNS

Popular DNS Providers

Step 4: Verify Domain

Step 5: SSL Certificate (Automatic)

Step 6: Start Using Your Domain

Customization Options

Branding Removal

Domain Configuration

API Reference

List Custom Domains

Add Custom Domain

Verify Domain

Remove Domain

Domain Statuses

Verification & Testing

Check DNS Propagation

Test SSL Certificate

Verify Board Access

Troubleshooting

DNS Not Verifying

SSL Certificate Not Issuing

CORS Errors

Domain Shows Error Page

Limitations

What You Can Customize

What You Cannot Customize

Technical Constraints

Pricing Tiers

Support

Setup Checklist

Timeline Expectations

Next Steps

Related Documentation