If your domain is registered somewhere else, you can keep it there and serve your BWEZE project on it. You add the domain to the project, publish two DNS records where the domain’s DNS is hosted today, and ask BWEZE to check them. This guide uses app.example.com; use your own name.
Without a domain yet, you can buy one through BWEZE, or claim a free *.bweze.app name, which skips DNS and goes live at once.
Before you start
- Your role. Only workspace owners and admins can connect domains and change DNS. Developers and members can see domains but not change them.
- Your token. An API token needs
dns:createto connect a domain,dns:readto verify it anddns:deleteto detach it. The DNS editor token template grants all three. - Your plan. Each plan allows a set number of custom domains at once: one on Free, more on paid plans (plan limits).
*.bweze.appnames don’t count. A domain over the limit is refused with403 plan_limit, and nothing is created.
Add the domain to your project
curl -X POST https://api.bweze.com/v1/projects/PROJECT_ID/domains \
-H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
-d '{ "domain": "app.example.com" }'
Or from the CLI:
bweze projects domains connect <projectId> app.example.com
BWEZE answers with the two DNS records to add:
| Record | What it does |
|---|---|
TXT |
An ownership challenge: it proves you control the domain |
CNAME |
Points the name at the BWEZE edge, the only way in from the internet |
Copy each record’s name and value from the response exactly.
Add the records at your current DNS provider
Add both records where your domain’s DNS is hosted today: your registrar, or whichever DNS provider your nameservers point to.
Keep your nameservers where they are. BWEZE runs its own nameservers, ns1.bweze.com and ns2.bweze.com, but they do not answer on the public internet yet, and the DNS docs ask you not to point a live domain at them until that notice is gone. For a domain you own, records at your current provider are the way to connect it today.
Two DNS rules apply:
- A name with a CNAME holds nothing else. RFC 1034 says that if a CNAME is present at a name, no other data should be, and RFC 1912 says a CNAME is not allowed to coexist with any other data. If
app.example.comalready has an A, AAAA, MX or TXT record, from an old host for example, remove it. - The apex can’t be a CNAME. The top of a zone,
example.comitself, carries the zone’s NS records and its SOA record (RFC 1034), so a CNAME there breaks the first rule. Connect a subdomain such aswwworapp, as the docs’ example does. The docs don’t describe connecting a bare apex domain.
If the name had other records before, resolvers may keep the old answer until its TTL runs out: the time, in seconds, a record may be cached (RFC 1035).
Verify
When both records are published, ask BWEZE to check them:
curl -X POST https://api.bweze.com/v1/domains/DOMAIN_ID/verify \
-H "authorization: Bearer bw_sk_..."
From the CLI, bweze projects domains verify DOMAIN_ID. The domain’s id is in the project’s list of custom domains: GET /v1/projects/{id}/domains, or bweze projects domains list <projectId>. If verification fails, fix the records and run it again; each call checks the DNS records again.
To see what resolvers see, query the records yourself with dig, where +short prints the answer alone:
dig +short CNAME app.example.com
dig +short TXT <name of the TXT record>
If nothing prints, the record is not published yet, or has not reached the resolver you asked.
HTTPS
There is no certificate to request. Every hostname gets one automatically, and the internet reaches your web services only through BWEZE’s edge, over HTTPS, on their bweze.app URL or your own domains. The docs don’t say which certificate authority issues it or how long issuance takes. Once the domain verifies, open https://app.example.com to check.
Detach
DELETE /v1/domains/{id} detaches the domain from the project. Then remove the two records at your DNS provider.
Errors you may see
| Code | Status | Meaning |
|---|---|---|
invalid_domain |
400 | Not a domain name BWEZE accepts |
plan_limit |
403 | Your plan allows no more custom domains |
domain_reserved |
409 | That *.bweze.app name is in use or reserved |
token_permission_denied |
403 | The token was not granted this action |
Full reference
The endpoints and CLI commands are in the domains docs, certificates in Networking, and BWEZE’s nameservers in DNS. For what each record type does, see DNS records.
Sources
- BWEZE docs: Domains
- BWEZE docs: Networking (custom domains and SSL)
- BWEZE docs: DNS
- BWEZE docs: API reference
- BWEZE docs: Workspaces and roles
- BWEZE docs: API tokens
- BWEZE docs: Pricing (plan limits)
- BWEZE docs: Error codes
- RFC 1034: Domain names, concepts and facilities
- RFC 1035: Domain names, implementation and specification
- RFC 1912: Common DNS operational and configuration errors
- BIND 9 manual pages: dig