Connect a domain you already own to a BWEZE project

Serve your BWEZE project on a domain registered elsewhere: one API call, two DNS records at your current provider, a verify step, then HTTPS.

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:create to connect a domain, dns:read to verify it and dns:delete to 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.app names don’t count. A domain over the limit is refused with 403 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.com already 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.com itself, carries the zone’s NS records and its SOA record (RFC 1034), so a CNAME there breaks the first rule. Connect a subdomain such as www or app, 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

Copy linkMarkdown

/ More guides

Build the next thing, from Rwanda.

Get started