# DNS records: what each type does and how to set them in BWEZE DNS

> A, AAAA, CNAME, MX, TXT, SRV and NS: what each record is for, why the apex cannot be a CNAME, how TTLs work, and who can edit records in BWEZE DNS.

Source: https://domains.bweze.com/guides/dns-records/ · Updated 2026-11-19

A DNS zone is a list of records, each with a name, a type, a TTL and a value. Resolvers ask for them by name and type. This guide covers the types BWEZE DNS accepts, the rules that catch people out, and how to set them.

BWEZE runs authoritative DNS on `ns1.bweze.com` and `ns2.bweze.com`. Those nameservers do not answer on the public internet yet. You can create zones and records now, but don't point a live domain's nameservers at them until the [DNS docs](https://docs.bweze.com/docs/dns) drop their notice. To serve a project on a domain you own today, [connect it](/guides/connect-a-domain/) with records at your current DNS provider.

## The record types

BWEZE DNS accepts seven types:

| Type    | What it holds                                       | Typical use                               |
| ------- | --------------------------------------------------- | ----------------------------------------- |
| `A`     | A host's IPv4 address                               | Point a name at a server                  |
| `AAAA`  | A single IPv6 address                               | The same, over IPv6                       |
| `CNAME` | The canonical name for an alias                     | Make `www` an alias of another name       |
| `MX`    | A preference and a mail exchange host               | Where mail for the domain is delivered    |
| `TXT`   | Text strings whose meaning depends on the name      | SPF, DKIM, DMARC and ownership checks     |
| `SRV`   | Priority, weight, port and target host of a service | Services found by `_service._proto` names |
| `NS`    | An authoritative name server                        | Delegate a subdomain to other nameservers |

In zone-file form they look like this (the SRV line uses the fictional service from RFC 2782):

```
@               A      203.0.113.10
@               AAAA   2001:db8::10
www             CNAME  app.example.net.
@               MX     10 mx1.mailhost.com.
@               TXT    "v=spf1 mx -all"
_foobar._tcp    SRV    0 1 9 old-slow-box.example.com.
lab             NS     ns1.otherhost.net.
```

- **MX.** With several mail hosts, the lower preference value is preferred (RFC 1035).
- **TXT.** The text means what the name it sits on says: an SPF policy at the apex, a DMARC policy at `_dmarc`. [SPF, DKIM and DMARC](/guides/spf-dkim-dmarc/) covers those three.
- **SRV.** Clients try the lowest priority first, and weight shares the load among targets of equal priority (RFC 2782).
- **NS.** An NS record says the named host is authoritative for a zone starting at that name (RFC 1035), which is how a subdomain is handed to other nameservers.

## CNAME rules

A CNAME makes its name an alias for another name. Three rules follow from the standards:

1. **Nothing else at that name.** 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. That includes MX and TXT records.
2. **No CNAME at the apex.** The top of a zone carries its NS records and its SOA record (RFC 1034), so a CNAME there breaks rule 1. RFC 1912 describes the result: the NS records are ignored, and every host in the domain with them. At the apex, use `A` and `AAAA` records.
3. **MX, NS and SRV point at real hosts.** The name in an NS or MX record must not be an alias (RFC 2181), and neither may an SRV target (RFC 2782). Point them at names with address records.

## TTL

The TTL is how long, in seconds, a resolver may cache a record (RFC 1035). In BWEZE DNS it runs from 60 to 86,400 seconds, one day, and defaults to 300. A short TTL lets a change reach everyone sooner. Before you move a record, lower its TTL and wait for the old TTL to pass.

## Set records in BWEZE DNS

Records live in a zone, so add the zone first:

```bash
curl -X POST https://api.bweze.com/v1/dns/zones \
  -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
  -d '{ "zone": "example.com" }'
```

BWEZE manages records as **record sets**: every record with one name and one type. Setting a record set replaces all of its records at once:

```bash
curl -X POST https://api.bweze.com/v1/dns/zones/example.com/records \
  -H "authorization: Bearer bw_sk_..." -H "content-type: application/json" \
  -d '{ "name": "@", "type": "MX", "ttl": 3600, "records": ["10 mx1.mailhost.com.", "20 mx2.mailhost.com."] }'
```

| Field     | Value                                            |
| --------- | ------------------------------------------------ |
| `name`    | The name in the zone; `@` is the zone's apex     |
| `type`    | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, `SRV` or `NS` |
| `ttl`     | Seconds, 60 to 86,400; default 300               |
| `records` | The values, one string per record                |

Editing is the same call. To add a third mail host to the set above, send all three values; to drop one, send the set without it. To delete a whole set, call `DELETE /v1/dns/zones/{zone}/records` with a body of `{ "name": "...", "type": "..." }`.

A name, type, TTL or value BWEZE does not accept fails with `400 invalid_record` or `invalid_dns_input`. `503 dns_unavailable` means the nameservers could not be reached; try again later.

The dashboard's DNS page does the same, and exports a zone as a BIND zone file.

## Who can change records

Every workspace role can see DNS. Only owners and admins can change it.

An API token needs a permission for each action:

| Action                   | Permission                                          |
| ------------------------ | --------------------------------------------------- |
| List and read zones      | `dns:read`                                          |
| Add a zone               | `dns:create` (not for tokens limited to some zones) |
| Set records              | `dns:update`                                        |
| Delete records or a zone | `dns:delete`                                        |

The **DNS editor** token template grants all four. A token limited to some zones sees and changes only those, and a token never does more than its owner's role allows.

## Full reference

Zones, record sets and permissions are in the [DNS docs](https://docs.bweze.com/docs/dns). Every DNS endpoint is in the [API reference](https://docs.bweze.com/docs/api#dns), and token scopes in [API tokens](https://docs.bweze.com/docs/api-tokens).

## Sources

- [BWEZE docs: DNS](https://docs.bweze.com/docs/dns)
- [BWEZE docs: API reference (DNS)](https://docs.bweze.com/docs/api)
- [BWEZE docs: API tokens](https://docs.bweze.com/docs/api-tokens)
- [BWEZE docs: Workspaces and roles](https://docs.bweze.com/docs/workspaces)
- [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 3596: DNS extensions to support IP version 6](https://www.rfc-editor.org/rfc/rfc3596)
- [RFC 1912: Common DNS operational and configuration errors](https://www.rfc-editor.org/rfc/rfc1912)
- [RFC 2181: Clarifications to the DNS specification](https://www.rfc-editor.org/rfc/rfc2181)
- [RFC 2782: A DNS RR for specifying the location of services (DNS SRV)](https://www.rfc-editor.org/rfc/rfc2782)
