# Zones and records A zone is the [Edge DNS](/en/documentation/platform/edge-dns/) object that holds one domain, and a record is one name, type, and set of values inside a zone. Edge DNS answers queries for the zone's domain from Azion's three nameservers once the domain's registrar delegates it to them. Each table below names a field's Azion Console label, Azion API field, and Azion CLI flag side by side. The value format of each record type is on [Record types](/en/documentation/platform/edge-dns/record-types/), and signing a zone is on [DNSSEC](/en/documentation/platform/edge-dns/dnssec/). --- ## Zone fields A zone carries a name for your own reference, the domain it serves, and an active state. In the Console, the fields sit on the **Create Zone** page and on the zone's **Main Settings** tab. | Console | API field | CLI flag | Type | Required | Default | Values | | --------------- | --------- | ----------------------------------- | ------- | --------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | `name` | `--name` | string | Yes | None | 1 to 50 characters. Identifies the zone in lists; it is not the domain. A longer name is refused with `10046`. | | **Domain Name** | `domain` | `--domain` | string | Yes | None | The domain the zone serves, such as `example.com`, up to 200 characters. It must end in a valid top-level domain (`19035`) and be hosted by no other zone in Azion (`19001` or `10012`). Fixed after creation. | | **Active** | `active` | `--active=true` or `--active=false` | boolean | Yes, in the API | On in the Console, `true` in the CLI | `true` answers the zone's names. `false` keeps the zone and its records, and the nameservers answer its names with `REFUSED`. | A zone's domain cannot change after creation: an update that sends `domain` is refused with `19036`, and the Console locks **Domain Name** on the **Main Settings** tab. To serve another domain, create another zone. An inactive zone is not answered: its names are answered `REFUSED`. Deactivation, like any change, can take a few minutes to reach every nameserver, which serve cached answers until then. For the cache behind that delay, refer to [How Edge DNS works](/en/documentation/platform/edge-dns/how-it-works/#caching-and-propagation). The API adds three read-only fields to a zone: `id`, the zone's identifier; `nameservers`, the three Edge DNS nameservers; and `product_version`, which reads `2.0`. `azion describe dns-zone --zone-id ` prints the same values as `ID:`, `Nameservers:`, and `Product Version:`. In the Console, the **Delete** action sits on the zone's row in the **Zones** list, and the edit page has no delete control. The dialog warns that the zone is deleted with all its associated settings and that the action cannot be reversed, and it asks you to type the zone's name. For the full procedure, refer to [Create, edit, or delete a zone](/en/documentation/guides/application-security/dns/edge-dns-configure-main-settings/). --- ## Record fields A record belongs to one zone: the API creates it under that zone's path, and the Console lists it on that zone's **Records** tab, in the **Create Record** and **Edit Record** drawers. A `POST` with `{"name":"www","type":"A","rdata":["192.0.2.1"],"ttl":3600}` stores the record below, and the API fills in the fields the request leaves out: ```json { "state": "executed", "data": { "id": 100172, "description": "", "name": "www", "ttl": 3600, "type": "A", "rdata": ["192.0.2.1"], "policy": "simple", "weight": 255 } } ``` | Console | API field | CLI flag | Type | Required | Default | Values | | ----------------- | ------------- | --------------- | ---------------- | ------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | `name` | `--name` | string | Yes | None | Relative to the zone: `www` answers for `www.example.com`, and `@` for the zone's domain itself. Never type the domain in the name. Up to 255 characters; each dot-separated label holds up to 63 letters, digits, `-`, `_`, or `*`. A `*` label makes a [wildcard](/en/documentation/platform/edge-dns/record-types/#wildcards). | | **Record Type** | `type` | `--type` | string | Yes | *A* in the Console | One of the 11 types in the table below. Any other value, such as `SOA`, is refused with `10039`. | | **Value** | `rdata` | `--rdata` | array of strings | Yes | None | One or more answers: one per line in the Console, an array in the API, and a repeated flag or a comma-separated list in the CLI. Up to 10 values for A, AAAA, ANAME, DS, MX, and NS; exactly one for CNAME and PTR; more than 10 values are accepted for TXT, CAA, and SRV. For each type, refer to [Record types](/en/documentation/platform/edge-dns/record-types/). | | **TTL (seconds)** | `ttl` | `--ttl` | integer | No | `3600` | How long a resolver may cache the answer. API: 1 to 2147483647. Console: the field accepts 0 to 604800. An [ANAME](/en/documentation/platform/edge-dns/record-types/#aname) record takes `20` only, and the Console pre-fills 20 for it. | | **Policy Type** | `policy` | `--policy` | string | No | *Simple*, `simple` | *Simple* (`simple`) answers with every value of the record. *Weighted* (`weighted`) lets several records share a name and type, each answering in proportion to its weight. | | **Weight** | `weight` | `--weight` | integer | No in the API; yes with *Weighted* in the Console | `255` in the API; the Console pre-fills `100` | 0 to 255, used only with `weighted`. A record's share of the answers is its weight over the sum of the weights. `0` keeps the record and never answers it. The Console disables the field for ANAME. | | **Description** | `description` | `--description` | string | No | Empty | Up to 45 characters. Tells apart weighted records with the same name and type. A longer value is refused with `10046`. | The API also returns `id`, the record's read-only identifier, which the record's CLI commands take as `--record-id`. A record name is relative to the zone, so Edge DNS adds the zone's domain to whatever you type. For example, in a zone whose domain is `example.com`, a record named `www.example.com` answers for `www.example.com.example.com`, and a query for `www.example.com` gets no answer from it. The Console shows the domain as a suffix after the **Name** field for that reason. The **Record Type** dropdown names each type with a short description. Each type's value format and rules are on its Record types entry: | Console option | API `type` | | --------------------------------------------- | ------------------------------------------------------------------ | | *A - IPv4 Address* | [`A`](/en/documentation/platform/edge-dns/record-types/#a) | | *AAAA - IPv6 Address* | [`AAAA`](/en/documentation/platform/edge-dns/record-types/#aaaa) | | *ANAME - Maps a name to another name* | [`ANAME`](/en/documentation/platform/edge-dns/record-types/#aname) | | *CAA - Certification Authority Authorization* | [`CAA`](/en/documentation/platform/edge-dns/record-types/#caa) | | *CNAME - Canonical name* | [`CNAME`](/en/documentation/platform/edge-dns/record-types/#cname) | | *DS - Delegation Signer* | [`DS`](/en/documentation/platform/edge-dns/record-types/#ds) | | *MX - Mail exchange* | [`MX`](/en/documentation/platform/edge-dns/record-types/#mx) | | *NS - Name Servers* | [`NS`](/en/documentation/platform/edge-dns/record-types/#ns) | | *PTR - Reverse DNS lookup* | [`PTR`](/en/documentation/platform/edge-dns/record-types/#ptr) | | *SRV - Location of server or service* | [`SRV`](/en/documentation/platform/edge-dns/record-types/#srv) | | *TXT - Text* | [`TXT`](/en/documentation/platform/edge-dns/record-types/#txt) | To delegate a subdomain to other nameservers, add an [NS](/en/documentation/platform/edge-dns/record-types/#ns) record on the subdomain's name. A name and type hold one simple record. A second record with the same name and type as a simple record is refused with `19004`; to answer with several values, put them all in one record's value. A CNAME also blocks every other type on its name, and a record of another type there is refused with `19018`. A saved zone or record needs no deployment step, but its answers reach the nameservers through a cache. A name that nobody queried before you created it answers within seconds. A name queried before it existed is answered `NXDOMAIN` for up to one hour, the SOA minimum. A change to an existing record can take a few minutes to reach every nameserver. For the details, refer to [How Edge DNS works](/en/documentation/platform/edge-dns/how-it-works/#caching-and-propagation). --- ## Nameservers and SOA Every zone is served by the same three Edge DNS nameservers and carries a start of authority (SOA) record that Azion writes. To make Edge DNS authoritative for a domain, delegate the domain to all three at its registrar. | Nameserver | IPv4 address | | ------------------ | --------------- | | `ns1.aziondns.net` | `179.191.160.2` | | `ns2.aziondns.com` | `179.191.161.2` | | `ns3.aziondns.org` | `179.191.162.2` | The nameservers are read-only. The API returns them in the zone's `nameservers` array, and the zone's **Main Settings** tab lists them under **Configure your Nameserver**, each with a copy button. On the **Zones** list, **Copy Nameserver Values** copies all three as one string joined by semicolons: `ns1.aziondns.net;ns2.aziondns.com;ns3.aziondns.org`. The SOA record names a zone's primary nameserver and contact, and sets its timers. You cannot write one: the API refuses `SOA` as a record type with `10039`. A query for a zone's SOA at `ns1.aziondns.net` returns these values: | SOA field | Value | | ------------------ | ------------------ | | Primary nameserver | `ns1.aziondns.net` | | Contact | `admin.azion.com` | | Refresh | 43200 seconds | | Retry | 7200 seconds | | Expire | 1209600 seconds | | Minimum | 3600 seconds | | SOA record TTL | 3600 seconds | The minimum is how long a negative answer, such as `NXDOMAIN` for a name that does not exist, may be cached, and Azion's nameservers cache it too, for up to one hour. For what that means when you add a record, refer to [How Edge DNS works](/en/documentation/platform/edge-dns/how-it-works/#caching-and-propagation). --- ## Permissions Two account permissions control Edge DNS. **View Edge DNS** grants access to view the zones on the account, without creating or removing them. **Edit Edge DNS** grants access to create, edit, and remove zones, and it requires **View Edge DNS**. For how permissions are granted, refer to [Teams permissions](/en/documentation/fundamentals/teams-permissions/). --- ## API and CLI The API base URL is `https://api.azion.com/v4`. Every request carries the header `Authorization: Token [TOKEN VALUE]`, with a [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/) of the account. The [Azion CLI](/en/documentation/devtools/cli/) runs the same operations: | Operation | API | CLI | | --------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- | | List zones | `GET /v4/workspace/dns/zones` | `azion list dns-zone` | | Create a zone | `POST /v4/workspace/dns/zones` | `azion create dns-zone --name --domain --active=true` | | Read a zone | `GET /v4/workspace/dns/zones/` | `azion describe dns-zone --zone-id ` | | Update a zone | `PATCH` or `PUT /v4/workspace/dns/zones/` | `azion update dns-zone --zone-id ` | | Delete a zone | `DELETE /v4/workspace/dns/zones/` | `azion delete dns-zone --zone-id ` | | List records | `GET /v4/workspace/dns/zones//records` | `azion list dns-record --zone-id ` | | Create a record | `POST /v4/workspace/dns/zones//records` | `azion create dns-record --zone-id ` | | Read a record | `GET /v4/workspace/dns/zones//records/` | `azion describe dns-record --zone-id --record-id ` | | Update a record | `PATCH` or `PUT /v4/workspace/dns/zones//records/` | `azion update dns-record --zone-id --record-id ` | | Delete a record | `DELETE /v4/workspace/dns/zones//records/` | `azion delete dns-record --zone-id --record-id ` | | Read DNSSEC | `GET /v4/workspace/dns/zones//dnssec` | `azion describe dnssec --zone-id ` | | Turn DNSSEC on or off | `PATCH` or `PUT /v4/workspace/dns/zones//dnssec` | `azion update dnssec --zone-id --enabled=true` | A `PATCH` changes only the fields you send. A `PUT` replaces the object: a zone takes `name` and `active`, and a record takes `name`, `type`, and `rdata`. A create or an update returns `{"state":"executed","data":{…}}`, a read returns `{"data":{…}}`, and a delete returns `{"state":"executed"}`. A list returns `count`, `total_pages`, `page`, `page_size`, and the objects in `results`. A list page holds up to 100 items, set with the `page_size` query parameter; the CLI takes `--page` and `--page-size`, with 50 items per page by default. Write a CLI boolean with an equals sign: `--active=true`, `--active=false`, `--enabled=true`, `--enabled=false`. --- ## Errors The API refuses each request below with HTTP `400` and changes nothing, except `10001` and `10002`, which return `401`, and `10004`, which returns `404`. Each entry of the `errors` array carries the code, the title, a `detail` sentence, and a `source` that names the field, such as `/data/name`. | Code | Title | Cause | What to do | | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `10002` | `Not Authenticated` | The request has no `Authorization` header: `Authentication credentials were not provided.` | Send `Authorization: Token [TOKEN VALUE]`. | | `10001` | `Authentication Failed` | The token is not valid: `Invalid authentication credentials.` | Send a valid personal token. | | `10004` | `Not Found` | The record does not exist, for example after a delete: `Not found.` | Check the zone and record IDs. | | `19035` | `Invalid Domain TLD` | A zone's `domain` does not end in a valid top-level domain: `Your domain must use a valid TLD.` | Use a domain with a valid top-level domain. | | `19001` | `Domain Already In Use` | Another account hosts the zone's `domain`: `Domain Belongs to Another Account.` | Use a domain that no other account hosts. A domain is hosted by one Azion account only. | | `10012` | `Unique Field` | The account already has a zone with this `domain`: `This field must be unique.` | Use the existing zone, or delete it first. | | `19036` | `Domain Cannot Be Modified` | An update sends a zone's `domain`: `The domain cannot be changed in update operations. Please create a new record instead.` | Create another zone for the other domain instead. | | `10046` | `Max Length` | A zone's `name` is longer than 50 characters: `Ensure this field has no more than 50 characters.` | Shorten the name to 50 characters. | | `10046` | `Max Length` | A record's `name` is longer than 255 characters: `Ensure this field has no more than 255 characters.`, together with `10076`. | Shorten the name to 255 characters. | | `10046` | `Max Length` | A record's `description` is longer than 45 characters: `Ensure this field has no more than 45 characters.` | Shorten the description to 45 characters. | | `10076` | `Invalid Pattern Match.` | A record's `name` has a label longer than 63 characters, or the name is longer than 255 characters. | Keep each label to 63 characters and the name to 255. | | `10039` | `Invalid Choice` | `type` is not one of the 11 record types, such as `SOA`: `"SOA" is not a valid choice.` | Send one of the 11 record types. | | `10059` | `Required Field` | The record has no `rdata`: `This field is required.` | Send at least one value in `rdata`. | | `10050` | `Min Value` | `ttl` is `0`: `Ensure this value is greater than or equal to 1.` | Send a TTL of 1 or more. | | `10068` | `Max Value` | `ttl` is above `2147483647`: `Ensure this value is less than or equal to 2147483647.` | Send a TTL of 2147483647 or less. | | `10068` | `Max Value` | `weight` is above `255`: `Ensure this value is less than or equal to 255.` | Send a weight from 0 to 255. | | `19004` | `Record Already Exists` | A simple record already has the same name and type, or the name already holds an SRV record: `There is already another record matching those data.` | Add the value to the existing record instead. | | `19018` | `CNAME Record Already Exists For Domain` | A record of another type, such as CAA, is added on a name that holds a CNAME: `A CNAME record was created for this domain. If you want to create another QTYPE, please remove CNAME record first.` | Remove the CNAME first, or use another name. | | `19005` | `Invalid CNAME` | A CNAME record is named `@`: `CNAMEs should not be used at the zone apex or domain root.` | Give the CNAME another name; at `@`, use an [ANAME](/en/documentation/platform/edge-dns/record-types/#aname) record for an Azion target. | | `19007` | `Invalid RData Size` | An A, AAAA, ANAME, DS, MX, or NS record has more than 10 values: `The 'rdata' cannot contain more than 10 items for the selected record type.` | Keep the record to 10 values. | | `19006` | `Invalid RData For CNAME Record` | A CNAME or PTR record has more than one value: `The 'rdata' cannot contain more than one item when 'type' is 'CNAME'.` The same title and detail are returned for a PTR record. | Send one value. | | `19003` | `Invalid IPV4` | An A record's value is not an IPv4 address, such as `300.1.1.1`: `Inform a valid value for an IPv4 record.` | Send a valid IPv4 address. | | `19002` | `Invalid Domain Name` | A CNAME record's value is an IP address: `Please enter the domain name following the format FQDN. IP addresses are not acceptable for this kind of record.` | Enter a hostname, not an address. | | `19021` | `Invalid NS Record Entry` | An NS record is named `@`: `NS records cannot be used at the zone apex or domain root.` | Name the subdomain you delegate. | | `19022` | `Invalid NS Record Answer` | An NS record's value is not a hostname: `Invalid value for NS type. You need to use FQDN format.` | Enter the nameserver's hostname. | | `19011` | `Invalid TTL For QTYPE` | An ANAME record's `ttl` is not `20`, including the default `3600`: `The TTL value is not valid for the selected record type.` | Keep the TTL at 20. | | `19016` | `Invalid ANAME Record Answer` | An ANAME record's value is outside the domains it accepts: `Only 'azioncdn.net', 'azionedge.net' and 'azionedge.com' subdomains are valid answers for ANAME records.` | Point the ANAME at a name under one of those three domains. | | `19017` | `Invalid Record Type For Weighted Policy` | A TXT or NS record has `policy` set to `weighted`: `The specified record type cannot be used with weighted policy.` | Use the `simple` policy for the record. | | `19019` | `Invalid SRV Record Entry` | An SRV record's name is not `_service._proto`, such as `*._tcp`: `Invalid SRV record entry format. Please fix the content to the following standard: '_service._proto'.` | Name the record `_service._proto`, such as `_sip._tcp`. | | `19024` | `Invalid TXT Record Answer Size` | A TXT value is longer than 1,000 characters: `You need to provide an answer with less than 1000 characters.` A value of exactly 1,000 characters is accepted. | Shorten the value to 1,000 characters. | | `10097` | `Invalid Page Size` | A list request sets `page_size` above `100`: `Page size must be between 0 and 100.` | Set `page_size` to 100 or less. | --- ## Related resources - [Record types](/en/documentation/platform/edge-dns/record-types.md): The value format, bounds, and rules of each of the 11 record types, and how wildcards match. - [DNSSEC](/en/documentation/platform/edge-dns/dnssec.md): How Azion signs a zone, its status values, and the DS record your registrar needs. - [Edge DNS limits](/en/documentation/platform/edge-dns/limits.md): Every bound on zones and records, and the zones and queries each plan includes. - [How Edge DNS works](/en/documentation/platform/edge-dns/how-it-works.md): How a query reaches Azion's nameservers, and how caching delays an added or changed record.