Custom Domains

Custom domains allow you to host your Aya profile on your own domain name with full DNS verification and automatic HTTPS.

Overview

Custom domain features:

Point any domain to your profile
Automatic DNS verification
HTTPS with automatic certificates
WWW prefix support
Multiple domains per profile (coming soon)
Locale routing preservation
Grace period for verification failures

Custom domains work for all profile types: individual, organization, and product profiles.

DNS Verification Process

Aya uses a 3-phase DNS verification system:

Phase 1: Direct IP Match

Domain A/AAAA records point to Aya’s origin IPs:

example.com.  IN  A     104.128.190.136
example.com.  IN  AAAA  2a0c:b840:2:1c::8cd4

Phase 2: CNAME Match

Domain CNAME points to Aya:

example.com.  IN  CNAME  aya.is.

www.example.com.  IN  CNAME  aya.is.

Phase 3: IP Resolution Match

This phase handles Cloudflare CNAME flattening and proxied setups where IPs may differ but routing is correct.

Domain resolves to same IPs as aya.is (for Cloudflare proxying):

example.com resolves to 104.21.X.X (Cloudflare edge IP)
aya.is resolves to 104.21.X.X (same edge IP)
→ Verification passes

Adding Custom Domain

Navigate to profile settings

Go to Settings → Custom Domains on your profile

Enter domain name

Input your domain (e.g., example.com or www.example.com)

Include www prefix if you want to use it. Apex and www are treated as separate domains.

Choose www prefix option

With www: Domain requires www (www.example.com)
Without www: Domain is apex (example.com)
Both: Redirect one to the other (requires two separate domain entries)

Configure DNS

Set up DNS records with your domain provider:Option A - Direct (recommended):

example.com.  IN  A     104.128.190.136
example.com.  IN  AAAA  2a0c:b840:2:1c::8cd4

Option B - CNAME (for subdomains):

www.example.com.  IN  CNAME  aya.is.

Option C - Cloudflare Proxied:

example.com.  IN  CNAME  aya.is.

(Enable orange cloud proxy in Cloudflare)

Wait for verification

DNS verification runs automatically every hour
Status: pending while verifying
Status changes to verified on success
You’ll receive notification when verified

Domain active

Once verified:

Profile accessible via custom domain
Automatic HTTPS certificate issued
All URLs work (stories, pages, etc.)
Locale routing preserved

DNS Configuration Examples

Apex Domain (example.com)

Without Cloudflare:

example.com.  300  IN  A     104.128.190.136
example.com.  300  IN  AAAA  2a0c:b840:2:1c::8cd4

With Cloudflare (CNAME flattening):

example.com.  300  IN  CNAME  aya.is.

Enable Cloudflare proxy (orange cloud)

Subdomain (www.example.com)

www.example.com.  300  IN  CNAME  aya.is.

Both Apex and WWW

Add both as separate custom domains:

example.com.      300  IN  A      104.128.190.136
www.example.com.  300  IN  CNAME  example.com.

Or use Cloudflare Page Rules to redirect one to the other.

Using CNAME for both apex and subdomain requires DNS provider that supports CNAME flattening (Cloudflare, Route53, etc.).

Verification Statuses

Pending

Initial state, verification not yet attempted or in progress

Verified

DNS verification passed, domain is active

Expired

Verification failed and grace period (24 hours) passed

Failed

DNS verification failed (within grace period)

Status Transitions

Pending → Verified  (DNS verification succeeds)
Pending → Failed    (DNS verification fails)
Verified → Failed   (Re-check fails, grace period starts)
Failed → Verified   (DNS fixed within 24 hours)
Failed → Expired    (24 hours pass without fix)
Expired → Verified  (DNS fixed and re-verified)

Expired domains stop routing traffic. Fix DNS and wait for next verification cycle (hourly) to restore service.

Grace Period

The 24-hour grace period prevents temporary DNS issues from breaking your site: Scenario:

Domain verified and working
DNS provider has temporary outage
Verification fails → status: failed
Grace period: 24 hours from last successful verification
If DNS restored within 24h → status: verified
If not restored → status: expired, domain stops working

Monitor custom domain status and set up alerts for verification failures.

URL Structure with Custom Domains

Custom domains preserve full URL structure: Profile:

https://example.com/en
https://example.com/ja

Stories:

https://example.com/en/stories/20250301-product-launch

Pages:

https://example.com/en/about
https://example.com/en/team

Search:

https://example.com/en/search?q=ai

Locale prefix is required in all URLs, even with custom domains. This ensures consistent multi-locale support.

Default Locale

Set a default locale for your custom domain:

{
  "domain": "example.com",
  "default_locale": "en"
}

Behavior:

https://example.com → redirects to https://example.com/en
If user has locale cookie, uses that instead
Preserves user language preference across visits

HTTPS Certificates

HTTPS is automatic and managed by Aya:

Certificates issued via Let’s Encrypt
Automatic renewal
No configuration needed
Supports wildcard for www variants

Certificate issuance begins after DNS verification succeeds. Allow 5-10 minutes for certificate propagation.

Webserver Sync

Once verified, domain must be synced to webserver:

{
  "domain": "example.com",
  "verification_status": "verified",
  "webserver_synced": true
}

Sync Process:

DNS verification succeeds
Domain added to webserver configuration
HTTPS certificate requested
Routing rules updated
webserver_synced set to true
Domain live

Webserver sync happens automatically within 5 minutes of verification. No manual action needed.

Multiple Domains (Roadmap)

Future support for multiple domains per profile:

Primary domain (canonical)
Secondary domains (redirects or mirrors)
Domain-specific locales
Domain-based branding

Cloudflare Integration

Using Cloudflare with Aya:

Recommended Settings

SSL/TLS Mode:

Set to Full (strict) for end-to-end encryption

DNS Records:

example.com.  IN  CNAME  aya.is.

Enable proxy (orange cloud) Page Rules:

Always Use HTTPS
Automatic HTTPS Rewrites

Cache Settings:

Respect Existing Headers
Browser Cache TTL: Respect Existing Headers

Cloudflare Benefits

DDoS protection
CDN edge caching
Faster global delivery
Additional SSL features
Analytics and monitoring
Firewall rules

Cloudflare Gotchas

CNAME flattening makes verification Phase 2 invisible
Proxy may show Cloudflare IPs instead of origin
Phase 3 verification handles this automatically
Purge Cloudflare cache after domain changes

DNS Providers

Compatible with all DNS providers:

Cloudflare

Recommended, best performance

Route53

AWS-native, CNAME flattening support

Namecheap

Budget-friendly, easy setup

Google Domains

Simple interface, reliable

GoDaddy

Popular, A/AAAA records only

Others

Any provider with A/AAAA or CNAME support

Troubleshooting

Domain shows 'pending' for long time

Verify DNS records are correct:

dig example.com A
dig example.com AAAA
dig example.com CNAME

Check DNS propagation (can take up to 48 hours globally)
Use DNS checker: https://dnschecker.org
Ensure no conflicting records
Wait for next verification cycle (runs hourly)

Domain verified but not accessible

Check webserver_synced status (should be true)
Wait 5-10 minutes for certificate issuance
Clear browser cache
Try incognito/private browsing
Check HTTPS certificate is valid
Verify firewall allows traffic

DNS verification keeps failing

Check IPs match exactly:
- IPv4: 104.128.190.136
- IPv6: 2a0c:b840:2:1c::8cd4
Or CNAME points to: aya.is.
Remove any conflicting records (multiple A records)
Disable DNS proxy temporarily to test
Check TTL isn’t too long (recommend 300s)

Cloudflare proxy causes issues

Ensure SSL/TLS mode is Full (strict)
Disable Cloudflare features one by one to isolate
Check Page Rules aren’t conflicting
Purge Cloudflare cache
Verify origin certificates are valid
Phase 3 verification should handle proxy IPs

Security Considerations

Keep domain registrar account secure. Unauthorized DNS changes can redirect traffic to malicious sites.

Best Practices:

Enable 2FA on domain registrar
Use strong passwords
Lock domain to prevent transfers
Monitor DNS changes (set up alerts)
Keep WHOIS information private
Review authorized users regularly

Performance Optimization

DNS Settings

Set low TTL (300s) during setup for faster changes
Increase TTL (3600s) once stable
Use Cloudflare for global anycast DNS
Enable DNSSEC for security

CDN (Cloudflare)

Enable orange cloud proxy
Configure caching rules
Use Polish for image optimization
Enable Brotli compression
Set up Workers for edge logic

Monitoring

Set up uptime monitoring
DNS monitoring for changes
SSL certificate expiry alerts
Performance monitoring (Core Web Vitals)

API Management

Add Custom Domain

curl -X POST https://api.aya.is/profiles/{profile_id}/domains \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "www_prefix": false,
    "default_locale": "en"
  }'

Check Verification Status

curl https://api.aya.is/profiles/{profile_id}/domains/example.com \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "domain": "example.com",
  "verification_status": "verified",
  "webserver_synced": true,
  "dns_verified_at": "2025-03-01T10:00:00Z",
  "last_dns_check_at": "2025-03-01T11:00:00Z"
}

Remove Custom Domain

curl -X DELETE https://api.aya.is/profiles/{profile_id}/domains/example.com \
  -H "Authorization: Bearer $TOKEN"

Best Practices

Domain Selection

Choose memorable, brandable domain
Shorter is better for typing
Avoid hyphens and numbers if possible
Match your brand/profile name
Consider .com for global reach
Use country TLDs for local focus

Setup Process

Set up DNS before adding domain on Aya
Use low TTL (300s) during initial setup
Test DNS propagation before submitting
Wait for verification before announcing
Keep old aya.is URLs working (redirects)
Update links gradually

Ongoing Management

Monitor DNS verification status weekly
Renew domain registration on time
Keep registrar contact info updated
Document DNS configuration
Test periodically from different locations
Set up alerts for verification failures

Next Steps

Profiles

Set up profile before adding domain

Stories

Publish content on your custom domain

Organizations

Use custom domains for organizations

Communities

Build community on branded domain

User Features

Community Features

Integrations

​Overview

​DNS Verification Process

​Phase 1: Direct IP Match

​Phase 2: CNAME Match

​Phase 3: IP Resolution Match

​Adding Custom Domain

​DNS Configuration Examples

​Apex Domain (example.com)

​Subdomain (www.example.com)

​Both Apex and WWW

​Verification Statuses

​Status Transitions

​Grace Period

​URL Structure with Custom Domains

​Default Locale

​HTTPS Certificates

​Webserver Sync

​Multiple Domains (Roadmap)

​Cloudflare Integration

​Recommended Settings

​DNS Providers

Cloudflare

Route53

Namecheap

Google Domains

GoDaddy

Others

​Troubleshooting

​Security Considerations

​Performance Optimization

​API Management

​Add Custom Domain

​Check Verification Status

​Remove Custom Domain

​Best Practices

​Next Steps

Profiles

Stories

Organizations

Communities

Build docs developers (and LLMs) love

Overview

DNS Verification Process

Phase 1: Direct IP Match

Phase 2: CNAME Match

Phase 3: IP Resolution Match

Adding Custom Domain

DNS Configuration Examples

Apex Domain (example.com)

Subdomain (www.example.com)

Both Apex and WWW

Verification Statuses

Status Transitions

Grace Period

URL Structure with Custom Domains

Default Locale

HTTPS Certificates

Webserver Sync

Multiple Domains (Roadmap)

Cloudflare Integration

Recommended Settings

DNS Providers

Troubleshooting

Security Considerations

Performance Optimization

API Management

Add Custom Domain

Check Verification Status

Remove Custom Domain

Best Practices

Next Steps