Custom Domains

Run LLM traffic on your own domain — branding, compliance, white-label, geo-routing, zero vendor lock-in.

Replacing the default acme.api.hydite.com with api.acme.com looks like a one-line DNS change — under the hood it solves six real problems at once:

• Brand consistency — every caller sees "your AI service", not Hydite.
• White-label resale — when you build an LLM platform on top of Hydite, every downstream customer gets their own domain.
• Compliance fit — regulators routinely judge data flow by the calling domain's jurisdiction; owning it removes an entire class of audit headaches.
• Zero vendor lock-in — once your code calls api.acme.com, you can swap gateway vendors later without touching app code.
• Local stability — in mainland China, an ICP-filed domain is more resilient than overseas hosts.
• Geo distribution — api-cn / api-eu etc. let GeoDNS route users to the nearest AO instance.

This article goes from the simplest subdomain swap to enterprise-grade private mTLS + GeoDNS.

1. Three tiers#

Sections below are tagged ✦ L1 / ✦ L2 / ✦ L3.

2. ✦ L1 · Platform subdomain#

Easiest way in, every subscription tier supports it:

Dashboard → Workspaces → Domains → Edit Subdomain:

• You get <your-name>.api.hydite.com (e.g. acme.api.hydite.com).
• Cert is issued + renewed by Hydite — zero ops.
• Custom prefix subject to availability + naming policy.

Use it:

1
client = OpenAI(api_key="sk-hydite-...", base_url="https://acme.api.hydite.com/v1")

Right for early-stage teams that don't need branding or jurisdiction control.

3. ✦ L2 · BYO apex / subdomain#

Subscription Business and above can attach any domain you own.

Step 1 — register the domain#

Dashboard → Domains → Add Custom Domain → enter api.acme.com. Three ownership-verification options:

After verification the domain enters Pending.

Step 2 — point DNS to Hydite#

The dashboard shows a target CNAME (e.g. acme.edge.hydite.com). At your DNS provider:

1
api.acme.com.   CNAME   acme.edge.hydite.com.

Bare apex (acme.com with no subdomain) cannot use CNAME per DNS spec. Use a subdomain (api. / ai. / chat.), or enable CNAME flattening / Apex CNAME at providers like Cloudflare or DNSPod.

Step 3 — wait for ACME issuance#

Once DNS propagates, Hydite issues a Let's Encrypt cert via ACME:

• ⏱ First issuance: 30 seconds to ~5 minutes, depending on DNS propagation.
• 🔄 Auto-renewal: 60 days before expiry — never expires.
• 🔐 HSTS + OCSP stapling on by default; TLS 1.2 / 1.3.

The status flips from Pending to Active — green check, ready to use.

Step 4 — attach a Group (optional)#

By default, all Groups share the domain. To route by domain (e.g. brand A's domain → Group A):

Dashboard → Domains → Bind Group → pick a target. All requests to that domain inherit the Group's policy bundle (see API Key Groups).

Step 5 — switch app traffic#

1
client = OpenAI(api_key="sk-hydite-...", base_url="https://api.acme.com/v1")

Zero code change — full L2 setup in 5 minutes.

4. ✦ L3 · BYO certificate#

When you must use your own cert (corporate CA / EV / national crypto):

Dashboard → Domains → BYO Certificate:

• Upload PEM (fullchain.pem + privkey.pem) or PKCS12 / PFX.
• The system validates fingerprint, expiry and host matches, then displays the expiry.
• Configurable TLS version range (min 1.2 / 1.3) and cipher allow-lists.
• Webhook reminder 30 days before expiry — no auto-renewal, you upload the new cert.

Suitable for finance / government workloads. You can mix with ACME — most domains use ACME, specific hosts use BYO.

5. ✦ L3 · Private domain#

Hosts that resolve only inside the customer's network:

• Add ai.internal.acme.com → AO private endpoint to your private DNS (CoreDNS / Route 53 Private Zone / Aliyun PrivateZone).
• Pair with the Connected Self-Host Agent — calls never leave the VPC.
• Optionally enable mTLS — clients must present a cert signed by your corporate CA.

1
# Private domain config
2
domain: ai.internal.acme.com
3
exposure: private
4
tls:
5
  source: byo
6
  client_auth: require
7
  trusted_cas:
8
    - acme-internal-ca-v3
9
network:
10
  allowed_cidrs:
11
    - 10.0.0.0/8
12
    - 172.16.0.0/12

Ideal for financial production, regulated workloads and government / on-prem networks.

6. ✦ L3 · Multi-region GeoDNS#

Resolve a single public domain to the nearest AO instance:

1
api.acme.com   →   GeoDNS:
2
                     • CN users → cn.edge.acme.com  → Shanghai cluster
3
                     • EU users → eu.edge.acme.com  → Frankfurt cluster
4
                     • else      → us.edge.acme.com  → Virginia cluster

Dashboard → Domains → GeoDNS Routing has a built-in rule editor:

• Match by GeoIP region / ASN / custom priority.
• Health check — drops unhealthy regions in < 60s.
• Failover — falls back through priority list when primary is unhealthy.
• TTL — default 60s, range 30s–3600s.

Use cases:

• Global products that want lowest perceived latency.
• Cross-border compliance: EU users must hit EU clusters; mainland China users must hit local clusters.
• DR — auto-cutover on primary outage.

7. ✦ L3 · Multi-domain (1-to-N or N-to-1)#

Subscription Business covers 1 BYO apex; Enterprise is unlimited.

8. ✦ L3 · CDN & front-proxy compatibility#

Many customers already front their public domains with Cloudflare / Akamai / AWS CloudFront / Aliyun CDN. Hydite plays nice:

• Reverse proxy through CDN: forward api.acme.com to Hydite's edge — Hydite recovers the real client IP from X-Forwarded-For, auth and rate limiting work normally.
• Pass-through headers: CDN must forward Authorization, X-Hydite-* etc. — do not rewrite headers.
• Don't cache POST: every LLM call is a POST and must not be cached. GET /v1/models and other metadata endpoints can have short TTLs (< 60s).
• WebSocket: streaming calls should bypass CDN — many CDNs disable WebSocket / SSE long-connections by default.
• HTTP/3: Hydite's edge supports HTTP/3 / QUIC natively and interoperates with CDN HTTP/3.

Dashboard → Domains → Edge Settings ships a "known-good" matrix for popular CDNs. Five minutes of config, done.

9. Reference — full enterprise config#

1
domains:
2
  - host: api.acme.com
3
    exposure: public
4
    tls:
5
      source: acme
6
      hsts: true
7
      min_version: TLS1.2
8
    routing:
9
      bind_group: prod-api
10
    geo:
11
      cn: cn.edge.acme.com → group=prod-api-cn
12
      eu: eu.edge.acme.com → group=prod-api-eu
13
      default: us.edge.acme.com
14
15
  - host: ai.internal.acme.com
16
    exposure: private
17
    tls:
18
      source: byo
19
      client_auth: require
20
    routing:
21
      bind_group: backend-batch
22
    network:
23
      allowed_cidrs: [10.0.0.0/8]
24
25
  - host: api.customer-acme.com
26
    exposure: public
27
    tls:
28
      source: acme
29
    routing:
30
      bind_group: customer-acme
31
    branding:
32
      logo: https://acme.com/logo-cust.svg
33
      console_subdomain: console.customer-acme.com

10. Operating playbook#

Domain health#

The Domains list shows a status per host:

Status changes fire webhooks (Dashboard → Domains → Webhooks).

Failover & vendor swap#

1
A · Custom domain → Hydite edge → AO Routing

If any segment fails, app code never changes:

• DNS / cert outage → flip back to the platform subdomain in 5 minutes.
• Region outage → GeoDNS auto-cutover in < 60 seconds.
• Switching gateway vendor → just point the CNAME elsewhere; app code unchanged.

That's the actual meaning of "zero lock-in via custom domains".

Release a domain#

Dashboard → Domain → Release:

• Stops accepting traffic for that host within 5 seconds.
• Detaches the Group, removes the cert, cleans GeoDNS rules.
• Recoverable for 24 hours; permanent after.

11. Security hardening: CAA · DNSSEC · CT monitoring#

Hard-requirements that corporate security teams always ask about — Hydite supports them natively:

CAA records (Certification Authority Authorization)#

Publish CAA records in your DNS so only the CAs you whitelist can ever issue a cert for this host:

1
api.acme.com.   CAA   0 issue "letsencrypt.org"
2
api.acme.com.   CAA   0 issue "hydite-ca.com"       ; allow Hydite-managed ACME
3
api.acme.com.   CAA   0 issuewild ";"                ; forbid any wildcard issuance
4
api.acme.com.   CAA   0 iodef "mailto:secops@acme.com"  ; notify on policy violation

Even if an attacker social-engineers your DNS, no non-whitelisted CA can mint a cert for your host. Dashboard → Domains → Security periodically reconciles your CAA against the CA actually in use and alerts on drift.

DNSSEC#

If your DNS provider supports DNSSEC (Cloudflare / Route 53 / DNSPod / Aliyun), turn it on. Hydite provides a DS-record template; you paste it into your registrar and you're done. Benefits:

• Prevents resolution hijacking — most notably the "phantom CNAME" attack.
• Required by financial / regulated baselines (MLPS-3, PCI-DSS).

Certificate Transparency monitoring#

Every cert issued by Hydite's ACME lands in public CT Logs. Dashboard → Domains → CT Monitoring subscribes your host to CT feeds:

• Any unexpected issuance (CA breach or phishing cert) fires an alert within minutes.
• 2-year history retained for post-mortems.
• Webhook push to your SIEM / Slack / Feishu.

Defaults that ship on#

12. SDK quick reference#

All languages swap the same way — just point base_url at your custom domain.

Python (OpenAI SDK)#

1
from openai import OpenAI
2
3
client = OpenAI(
4
    api_key="sk-hydite-...",
5
    base_url="https://api.acme.com/v1",
6
    timeout=60.0,
7
    max_retries=2,
8
)
9
10
stream = client.chat.completions.create(
11
    model="claude-sonnet-4-5",
12
    messages=[{"role": "user", "content": "Hi"}],
13
    stream=True,
14
)

TypeScript (OpenAI SDK)#

1
import OpenAI from "openai"
2
3
const client = new OpenAI({
4
  apiKey: process.env.HYDITE_KEY,
5
  baseURL: "https://api.acme.com/v1",
6
  maxRetries: 2,
7
})

Go#

1
client := openai.NewClient(
2
    option.WithAPIKey(os.Getenv("HYDITE_KEY")),
3
    option.WithBaseURL("https://api.acme.com/v1"),
4
)

Java (LangChain4j)#

1
OpenAiChatModel model = OpenAiChatModel.builder()
2
    .apiKey(System.getenv("HYDITE_KEY"))
3
    .baseUrl("https://api.acme.com/v1")
4
    .modelName("claude-sonnet-4-5")
5
    .build();

curl (your most reliable pre-launch probe)#

1
curl https://api.acme.com/v1/chat/completions \
2
  -H "Authorization: Bearer sk-hydite-..." \
3
  -H "Content-Type: application/json" \
4
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"ping"}]}'

Anthropic Messages style#

Hydite also serves /v1/messages:

1
curl https://api.acme.com/v1/messages \
2
  -H "x-api-key: sk-hydite-..." \
3
  -H "anthropic-version: 2023-06-01" \
4
  -d '{"model":"claude-sonnet-4-5","max_tokens":64,"messages":[{"role":"user","content":"Hi"}]}'

13. Zero-downtime migration: platform subdomain → BYO domain#

Large customers already have N internal systems / partners calling acme.api.hydite.com and want to move to api.acme.com without downtime. The standard play is dual-domain parallel run:

1
Phase 0 (start):    callers → acme.api.hydite.com
2
Phase 1 (parallel): callers → acme.api.hydite.com + api.acme.com
3
                              both serve, same Group & key pool
4
Phase 2 (rollout):  migrate callers one batch at a time
5
Phase 3 (single):   callers → api.acme.com
6
Phase 4 (cleanup):  release acme.api.hydite.com (optional)

Dashboard → Domains → Aliases supports multiple live hosts on the same Group — certs, rate limits, audit are all shared. Zero downtime, and each caller changes base_url exactly once.

Suggested schedule#

14. Per-domain observability#

Beyond basic health, Dashboard → Domains → Metrics emits per-host signals:

API:

• GET /domains/{host}/metrics?range=24h
• GET /domains/{host}/tls-handshakes
• GET /domains/{host}/ct-events

Push to Prometheus / Datadog / customer SIEM — see Shared Edge · Observability.

15. Pre-launch checklist#

Walk through this 10-item list before cutting L2 / L3 traffic. Error rate ≈ 0 when followed:

• DNS resolves to the correct CNAME on major recursive resolvers (1.1.1.1, 8.8.8.8, 9.9.9.9, AliDNS, TencentDNS, Quad9).
• dig +trace api.acme.com shows no surprising redirects.
• openssl s_client -connect api.acme.com:443 -servername api.acme.com returns a full chain with Verify return code: 0 (ok).
• HTTP → HTTPS works: curl -I http://api.acme.com returns 308 + Strict-Transport-Security.
• Real curl POST to /v1/chat/completions with a live key succeeds.
• Rate limits fire: call with an over-quota key and confirm 429 + X-Hydite-Limit-Layer.
• Correct Group binding: Overview dashboard shows traffic on the expected Group.
• CT Logs contain this issuance and no surprises.
• Fallback host (old subdomain) still works — keep it up for at least 2 weeks as a rollback anchor.
• Webhook alerts wired (cert expiry, DNS drift, CT anomalies).

Dashboard → Domains → Pre-launch Checklist auto-runs the first 8 and flips green when they all pass.

16. Troubleshooting FAQ#

Q1 — DNS set for 24h, dashboard still says Pending?#

Three common causes:

1. Ownership verification failed — dig TXT _hydite-verify.api.acme.com should return the string from the dashboard.
2. Wrong CNAME target — dig CNAME api.acme.com must match the dashboard target; don't layer a CDN in between during initial setup (breaks HTTP Challenge).
3. Bare-apex with CNAME — see §3 on CNAME flattening.

Q2 — ACME issuance keeps failing with urn:ietf:params:acme:error:connection?#

A security product (WAF / Cloudflare Bot Fight Mode) is blocking the challenge. Fixes:

• Switch to DNS-01 validation (TXT record, no HTTP roundtrip).
• Or whitelist /.well-known/acme-challenge/* at the CDN / WAF.

Q3 — Clients intermittently report SSL_ERROR_BAD_CERT_DOMAIN / ERR_CERT_AUTHORITY_INVALID?#

• Clock skew on client > 5 min breaks cert validation — fix NTP.
• Missing intermediate CA in old Android / old Java — ISRG Root X1 might be absent. Upgrade client or use BYO Cert with your corporate CA.
• CDN sending wrong SNI — ensure the CDN forwards SNI = api.acme.com, not its default host.

Q4 — Latency suddenly spikes for one region?#

Dashboard → GeoDNS → Health:

• If the region shows 🔴 Unhealthy, GeoDNS should have cut it in < 60s — verify the cutover happened.
• If the region is healthy but users are slow, it's almost always a local ISP DNS misroute (sending CN users to overseas clusters). Enable EDNS Client Subnet or use our managed edgedns.hydite.com.

Q5 — CDN in front returns 421 Misdirected Request?#

The CDN rewrote the Host header to its internal value. Hydite's edge keys Groups off Host + SNI — mismatch = 421. Fix:

• Set the CDN to Preserve Host Header / Forward Original Host.
• Make sure CDN → Hydite origin uses the same SNI as the public host.

Q6 — HTTP/3 (QUIC) occasionally fails, falling back to HTTP/2?#

• Check egress firewall allows UDP/443.
• Mobile NAT windows are short — transient fallback to H2 is normal.
• Force HTTP/2 if needed: Dashboard → Domains → Protocol → disable_h3.

Q7 — During migration, will the same workload be billed twice?#

No. Multiple domains bound to the same Group share one ledger — quotas, budget, audit all apply once. Billing is per key / per Group, not per domain. The "domain" column in Billing is just a dimension, not a multiplier.

Q8 — Need to restore a released domain?#

Within 24 hours click Restore in the dashboard — cert, Group binding, GeoDNS rules all come back as-is. After 24h, rerun Step 1–3.

Q9 — Need a wildcard cert *.acme.com?#

Supported on L3. ACME wildcards can only validate via DNS-01 (no HTTP Challenge), so delegate _acme-challenge.acme.com as CNAME to Hydite for auto-renewal.

Q10 — Compliance requires 45-day notice before cert expiry, with 3 separate notifications?#

Dashboard → Domains → Webhooks → Cert Expiry:

• Multi-threshold alerts at 45 / 30 / 15 / 7 / 1 days.
• Fan out to Feishu / DingTalk / Slack / email / SIEM simultaneously.
• ServiceNow / Jira auto-ticketing connectors available.

17. Tier matrix#

18. Anti-patterns#

• ❌ CNAME on bare apex — not allowed per DNS spec; use a subdomain or enable CNAME flattening.
• ❌ CDN dropping Authorization — every request 401s.
• ❌ CDN caching POST — two customers can see each other's completions. Critical data leak.
• ❌ Same domain bound to multiple Groups — routing collisions; split by subdomain or merge into one Group.
• ❌ Private domain leaked to public DNS — equivalent to publishing your VPC entry.
• ❌ No expiry monitor on BYO cert — site goes dark on the day of expiry.
• ❌ DNS TTL > 1 hour — failover becomes a multi-hour event.

Next steps#

• Multi-key governance → API Key Groups
• Quotas & limits → Rate Limiting
• Endpoint catalogue → API Reference
• Full enterprise mTLS / private network → Dedicated Instance