Custom domains

Every gateway keeps a permanent Bazantic URL. You can put a better name on it:

• A custom handle, such as acme.bazgateway.com. This needs no DNS work.
• A custom domain, such as api.acme.com. This needs two DNS records on a domain you own.

When a custom domain is active, Bazantic advertises it as the gateway's URL. The catalog listing, the agent card, the MCP endpoint, and the 402 payment challenges all use that URL. A handle does the same when no custom domain is active.

Choose a form

You can hold both. A custom domain wins when both are live.

Claim a custom handle

1. Open the gateway in the dashboard.
2. Find the Custom handle card.
3. Keep the suggested handle, or type a different one.
4. Press Claim handle.

The new URL is live within a minute.

A handle is one DNS label. It must obey these rules:

• 3 to 63 characters.
• Lowercase letters, numbers, and hyphens only.
• The first and last character must not be a hyphen.
• It must be unique across Bazantic.
• It must not be a reserved name. Bazantic reserves three classes of names:
  • Common infrastructure labels, such as www, api, mail, auth, login, dev, and staging.
  • Bazantic product names, such as bazantic, askbaz, and gateway.
  • Major brand names, such as github and stripe.

Every gateway carries a suggested handle from the day you deploy it. The suggestion is not live until you claim it. Until then the gateway advertises its slug.

Add a custom domain

Before you start, make sure you have these three things:

• A domain that you control.
• Access to the DNS records for that domain.
• The gateway:write permission on the account that owns the gateway.

Step 1 — Pick a hostname

Use a subdomain, such as api.acme.com or gateway.acme.com. Bazantic does not serve an apex domain such as acme.com.

The hostname must be lowercase ASCII. Internationalized domain names are not supported.

Step 2 — Add the domain to the gateway

In the dashboard, open the gateway and find the Custom domain card. Type the hostname and press Add domain.

From the terminal, use the CLI:

baz gateway domains add my-gateway api.acme.com

Bazantic answers with two DNS records and sets the status to Pending ownership.

Step 3 — Create the two DNS records

Add both records at your DNS provider. Copy the values from the card or from the CLI output. The token is unique to your domain.

The TXT record proves that you control the domain. The CNAME record sends traffic to Bazantic. Both records must stay in place for as long as you use the domain.

Four provider details cause most failures:

• Turn the proxy off. On Cloudflare, set the record to DNS only, the grey cloud. A proxied record hides the CNAME and the check fails.
• Watch for an appended zone. Some registrars add the zone to the host you type. If your provider does this, enter _baz-challenge.api and not the full name.
• Remove a conflicting AAAA record. The hostname must resolve through the CNAME alone.
• Allow the certificate authority. If your zone uses CAA records, add 0 issue "letsencrypt.org". A zone with no CAA record needs no change.

Step 4 — Verify the records

Press Verify in the dashboard, or run this command:

baz gateway domains verify my-gateway

Bazantic reads your TXT, CNAME, CAA, A, and AAAA records from public resolvers. The card shows the TXT and CNAME results, and names any A, AAAA or CAA problem.

A new DNS record is not visible everywhere at once. Your provider states a propagation time. If the first check fails, wait and check again. Bazantic also re-checks every pending domain for you every few minutes, so you can leave the page and come back.

Manual verification is limited to six attempts per hour for each hostname. The button shows a countdown when you reach the limit.

Step 5 — Wait for the certificate

When both records pass, the status moves to Pending certificate. Bazantic requests the certificate for you. You do not do anything in this step.

The status becomes Active when the certificate is ready. Your gateway then answers on https://api.acme.com, and Bazantic advertises that URL.

TLS renewal and recovery

Fly issues and renews the certificate for your hostname. Bazantic does not hold the certificate or its private key. It checks the Fly certificate state and manages the operator response when a renewal is at risk or fails.

A renewal-risk observation does not interrupt traffic. The custom hostname stays active while Fly works to renew its certificate. DNS ownership and TLS health are separate: a domain can have healthy DNS while its certificate needs attention.

If Bazantic confirms that TLS is unavailable, new catalog and dashboard URLs use the gateway's canonical URL until Fly recovers. Bazantic does not redirect requests from the failed custom hostname. A caller or agent that pinned that hostname must wait for Fly to restore its certificate; the original domain claim and DNS records remain in place, and you can repair or remove the claim.

How the certificate is issued

Fly issues a TLS certificate for your hostname through Let's Encrypt. The process runs in this order:

1. Your TXT and CNAME records pass the checks in step 4. Bazantic requests no certificate before this point.
2. Bazantic asks the Fly gateway edge to order a certificate for your exact hostname.
3. Let's Encrypt validates the order over HTTP, through the CNAME record you created. You add no further DNS record for the certificate.
4. The edge installs the certificate. Bazantic reads the certificate state, and moves the domain to Active.

Issuance usually completes in a few minutes. The status stays at Pending certificate until the certificate is ready.

Renewal is automatic. Keep the CNAME record and any CAA record in place, and you do not touch the certificate again.

The certificate covers the exact hostname you added. It does not cover a wildcard, and it does not cover other names in your zone.

What the statuses mean

A domain that is degraded keeps serving traffic while the certificate is valid. Bazantic releases the domain if the DNS stays wrong for 30 days.

These DNS statuses do not report certificate health. A domain can remain DNS-active while Bazantic watches its TLS renewal separately. If TLS fails, the failed claim stays removable even though Bazantic stops using the custom hostname in new URLs.

A domain that never reaches Active expires after 7 days. Remove it and add it again to get a new token.

Fix a failed check

The card names one reason at a time. The CLI prints the same reason as a code.

Limits

Remove a custom domain

Press Remove on the card, or run this command:

baz gateway domains rm my-gateway

The hostname stops serving traffic within a minute, and Bazantic advertises the previous URL again. Callers that pinned the custom hostname get a TLS error, so publish the change before you remove the domain. This is different from a confirmed TLS failure: in that case Bazantic keeps the claim and DNS records, but uses the canonical URL for new catalog and dashboard links while Fly recovers.

Ownership proof still stands in the way of that takeover. A released hostname is never served again until somebody proves control of it one more time, with a fresh token in a new TXT record. To use the hostname again yourself, add it again and repeat step 3.

Do it from the CLI

Every step above has a CLI command. Sign in first with baz login.

baz gateway domains add my-gateway api.acme.com   # claim the hostname, print the records
baz gateway domains status my-gateway             # status, per-record state, last check
baz gateway domains verify my-gateway             # run the checks now
baz gateway domains rm my-gateway --yes           # release the hostname

Add --json to any of these commands for a machine-readable result. See Command line for the rest of the CLI.