Start here

Hackathon guide

Everything your team needs on the day: what Itoka gives you, how to set up in ten minutes, how to get your free subdomain, and some ideas to build.

What every team gets

	What	Cost
DNS hosting	Host DNS for any domain your team owns, with records live on both nameservers in about a second.	Free
Free subdomains	Up to three names like `yourteam.itoka.dev`, live the moment you claim them. They stay yours after the hackathon.	Free
The API and SDK	Everything the dashboard does, from code. A typed JavaScript/TypeScript client.	Free
Webhooks	Signed events to your server when records change or an order completes.	Free

Set up in ten minutes

One person creates the team's account at itoka.ng/signup and confirms the email. Claiming a free subdomain and creating API keys need a confirmed email; until then they answer 403 email_unverified.
Turn on two-factor authentication in Settings. You need it to create API keys.
Invite your teammates as managers of your zones from each zone's page ("Who can manage"). They sign up with the invited email and see the zone in their own dashboard.
Get your names: claim a free subdomain (below), up to three per account. Already own a domain? Add it as a zone and point its nameservers at Itoka; DNS hosting is free too.
Create an API key under API keys, from the account that owns the zones. For a hackathon project, choose All your zones and the permissions your code uses; see the table below. Keep the key in an environment variable on your server, never in a browser or a public repo.
Teammates’ keys and shared zones
All your zones means the zones the key's account owns. A teammate who manages your zone and makes their own key must pick the shared zone by name when creating it, or the key gets 404 for that zone.

To…	Give the key
Read and change DNS records	Read records, Write records
Claim free subdomains or add zones from code	Manage zones
Add and manage webhooks from code	Manage webhooks
Issue Let’s Encrypt certificates with DNS-01 only	DNS-01 challenges

Claim a free subdomain

In the dashboard: Add a zone → Get a free subdomain. Type a name, and if it's available, claim it. Or from code:

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

Names are 3 to 30 letters, digits and hyphens. Some are reserved (www, api, mail, login…), and names containing brands people impersonate (banks, payment apps) aren't available. Each account can have three.

Ideas to build

Preview deployments with real names. On every pull request, add pr-123.yourteam.itoka.dev as a CNAME to the preview, and remove it when the PR closes.
Dynamic DNS. A Raspberry Pi or home server keeps home.yourteam.itoka.dev pointing at its current IP with records.upsert every few minutes.
A DNS change feed. Webhooks to Slack, Discord or WhatsApp whenever a record changes, with who changed what.
One-click setup for small businesses. Buy a domain and apply the Google Workspace or Zoho Mail preset in one flow.
Wildcard certificates. A key with only DNS-01 challenges lets certbot, lego or Caddy issue *.yourteam.itoka.dev certificates without touching other records.
A domain health checker. Search names, then check MX, SPF and DMARC and explain what's missing in plain English.

Rules

No phishing, impersonation, malware or spam. Free subdomains used for any of these are suspended at once: their records are removed.
Stay within the limits: 300 API requests a minute per key. See Errors and limits.
Register domains with true registrant details. The registrant is the legal owner, and the registry can check.

Help on the day

Every error from the API says what went wrong and how to fix it; read the message and fix first, then Troubleshooting. Recipes has ready-made code for hosting your site, dynamic DNS, preview names and certificates. Otherwise email hello@itoka.ng with your account email and what you were doing.