DomainsDocsSign in
Guides

Zones and nameservers

A zone is a domain whose DNS Itoka serves. Adding one takes three steps: add it, prove it's yours, and point its nameservers at Itoka.

  1. Add the domain. POST /zones with its name. It comes back with status: "unverified" and a TXT record to publish.
  2. Prove it's yours. Publish the TXT record at your domain's current DNS host. Itoka checks on its own (every 30 seconds at first), or ask now with POST /zones/{zone}/verification/check. Once found, the zone is created on ns1 and ns2.
  3. Switch nameservers. At your registrar, replace the nameservers with ns1.itoka.ng and ns2.itoka.ng. Itoka watches the registry and the parent zone and tells you when the switch is live.

Adding a domain

curl https://api.itoka.ng/api/v1/zones \
  -H "Authorization: Bearer $ITOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ojaara.ng"}'

The key needs zones:manage for all zones. Only registrable domains can be added (ojaara.ng, not shop.ojaara.ng): add the domain and put records for its subdomains inside it. Up to 20 domains can wait for verification at once, and unverified domains are dropped after 30 days. DELETE /zones/{zone} removes one that isn't verified yet.

Why verification is strict

ns1 and ns2 answer for every zone they hold, so a zone created for someone else's domain would hijack it. The TXT record counts only when every nameserver the parent zone lists for the domain answers with it, and only if those nameservers aren't already Itoka's. If your domain already points at ns1/ns2.itoka.ng, point it back at a host where you can publish the record first. verification.message always says what's wrong.

Delegation

zone.delegation is where the registry (WHOIS) and the parent zone (for example the .ng servers) point the domain:

stateMeans
waitingThey don’t point at Itoka yet. Registrars usually push a change within an hour.
liveBoth list exactly ns1.itoka.ng and ns2.itoka.ng. Your records are answering.
problemThey point at Itoka only partly (just one of the two, or alongside other nameservers). The message says what to fix.

Itoka checks every 30 seconds for new zones, backing off to hourly after a week, and every 6 hours once live. POST /zones/{zone}/delegation/check checks now (at most every 5 seconds per zone). The zone.delegation_changed webhook tells you the moment it goes live.

Zone status

statusMeans
unverifiedAdded; waiting for the TXT record. Nothing is served.
waitingOn ns1 and ns2, but the domain doesn’t point at them yet.
liveDelegated and served by both nameservers, in sync.
errorSomething needs attention: ns2 behind ns1, a delegation problem, or a suspended free subdomain. status_note explains.

Sharing a zone

A zone has one owner and any number of managers. Managers edit records and see the zone in their own dashboard; only the owner can change who has access or hand the zone over. Invite managers from the zone's page in the dashboard. A key's "all zones" doesn't include zones shared with you; pick them by name when you create the key.

Deleting a zone

The owner can delete a zone from the foot of its page: it and all its records leave ns1 at once and ns2 within seconds. Managers and API keys lose access to it; the audit log keeps its history. If the domain still uses Itoka's nameservers, it stops working everywhere, so move the nameservers first. Deleting a free subdomain frees one of your three.

curl -X DELETE "https://api.itoka.ng/api/v1/zones/ojaara.com?confirm=ojaara.com" \
  -H "Authorization: Bearer $ITOKA_API_KEY"

confirm must be the zone's name; without it the API answers 409 zone_verified, so a script tidying up unverified domains can't delete a live one. A domain registered through Itoka that still uses Itoka's nameservers can't have its zone deleted (409 domain_registered_here): change its nameservers on the domain's page first, or transfer it away.

PreviousAPI keys