API keys
Programs authenticate with an API key: a secret that starts with itk_live_, sent as a bearer token.
GET /api/v1/zones HTTP/1.1
Host: api.itoka.ng
Authorization: Bearer itk_live_7f3aQm...Creating a key
Create keys in the dashboard under API keys. You need two-factor authentication turned on, and Itoka asks for a code each time. For each key you choose:
- A name you'll recognise: every change a key makes is in the audit log under its name.
- Zones: All your zones, or particular ones. "All" covers the zones your account owns, including ones added later. A zone shared with you (you're its manager) must be picked by name, so an invitation never quietly widens a key.
- Permissions, from the table below.
- An expiry: never, or in 30 days, 90 days or a year.
The key is shown once. Itoka keeps only a hash, so a lost key can't be recovered: revoke it and create another. Revoking takes effect at once.
Permissions
| Permission | Allows |
|---|---|
records:read | Read zones and their records, propagation and setup checklists. |
records:write | Create, change and delete records; apply presets; import records. |
zones:manage | Add domains and claim free subdomains (keys for all zones only). |
acme:dns01 | Only TXT records named _acme-challenge (or _acme-challenge.<sub>): read, create and delete. For certificate tools. |
domains:read | List domains and orders. |
domains:buy | Contacts, quotes, promo code checks and orders (keys for all zones only, since each domain adds a zone). |
domains:manage | Change a domain’s nameservers, lock it, and turn auto-renew on. |
webhooks:manage | Everything under /webhooks (keys for all zones only: webhooks get events for the whole account). |
Some things are dashboard-only, whatever the permissions: unlocking a domain, revealing its transfer code, creating pay links, and changing who manages a domain or zone.
Orders placed with a key
An order placed with a key belongs to the person who created the key, and their email must be confirmed. If that person's account is deleted, the key can't buy. A key can place 20 orders an hour.
When a key is refused
| Status | Code | Means |
|---|---|---|
| 401 | signed_out | No Authorization header at all, so the API took you for a signed-out dashboard visitor. Send Authorization: Bearer itk_live_…. |
| 401 | invalid_key | The header isn’t “Bearer …”, or the key is mistyped, revoked or expired. The message says which. |
| 403 | forbidden | The key lacks a permission or the zone (the message names what to add), or the endpoint is dashboard-only. |
| 429 | rate_limited | Over 300 requests a minute for this key. Wait for Retry-After seconds. |