# 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.

Source: https://domains.bweze.com/guides/connect-a-domain/ · Updated 2026-11-19

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](/guides/buy-a-domain/), 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](https://docs.bweze.com/docs/pricing#plans)). `*.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

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://docs.bweze.com/docs/domains#connect-a-domain-you-own---post-v1projectsiddomains), certificates in [Networking](https://docs.bweze.com/docs/networking#custom-domains-and-ssl), and BWEZE's nameservers in [DNS](https://docs.bweze.com/docs/dns). For what each record type does, see [DNS records](/guides/dns-records/).

## Sources

- [BWEZE docs: Domains](https://docs.bweze.com/docs/domains)
- [BWEZE docs: Networking (custom domains and SSL)](https://docs.bweze.com/docs/networking)
- [BWEZE docs: DNS](https://docs.bweze.com/docs/dns)
- [BWEZE docs: API reference](https://docs.bweze.com/docs/api)
- [BWEZE docs: Workspaces and roles](https://docs.bweze.com/docs/workspaces)
- [BWEZE docs: API tokens](https://docs.bweze.com/docs/api-tokens)
- [BWEZE docs: Pricing (plan limits)](https://docs.bweze.com/docs/pricing)
- [BWEZE docs: Error codes](https://docs.bweze.com/docs/errors)
- [RFC 1034: Domain names, concepts and facilities](https://www.rfc-editor.org/rfc/rfc1034)
- [RFC 1035: Domain names, implementation and specification](https://www.rfc-editor.org/rfc/rfc1035)
- [RFC 1912: Common DNS operational and configuration errors](https://www.rfc-editor.org/rfc/rfc1912)
- [BIND 9 manual pages: dig](https://bind9.readthedocs.io/en/stable/manpages.html)
