API keys

Scripts, the CLI and the SDKs authenticate with an API key, sent as Authorization: Bearer <key>. There are two kinds. They travel the same way, and Dinio tells them apart by their prefix.

Key	Prefix	Belongs to	Can reach
Personal key	`du_`	your user	Everything your user can: DNS hosting in the zones you own or administer, your DNS filtering identities and lists, your own account.
Zone key	`dz_`	one zone	DNS hosting in that zone only: its records, health checks, geo bans, redirects, certificates, zone files and statistics. It cannot create zones, and it has no access to DNS filtering.

Use a zone key for anything that only needs one zone — a CI job that updates a record, an ACME client that writes _acme-challenge TXT records. A leaked zone key exposes one zone, not your account.

DNS filtering belongs to your user, not to a zone, so it always needs a personal key: a zone key gets 403 FORBIDDEN on every client identity and sinkhole route.

Sending a key

curl -H "Authorization: Bearer $DINIO_API_KEY" https://api-dinio.bitelex.com/api/v1/zones

dinio profile set-key default   # prompts for the key, hidden
dinio auth status

import { DinioClient } from '@dinio/sdk';

const dinio = new DinioClient({
  baseUrl: 'https://api-dinio.bitelex.com',
  apiKey: process.env.DINIO_API_KEY,
});

let client = dinio_sdk::Client::builder()
    .base_url("https://api-dinio.bitelex.com")
    .api_key(std::env::var("DINIO_API_KEY")?)
    .build()?;

A missing header is 401 UNAUTHENTICATED; an unknown or revoked key is 401 INVALID_API_KEY. A token without the du_ or dz_ prefix is not read as an API key at all, and gets 401 INVALID_TOKEN. A valid key that is not allowed to touch a resource gets 403 FORBIDDEN.

Getting a key

Dinio generates every key. You issue your first personal key in the Dinio web app. With it you can create zones, issue a key for each zone, and replace or revoke both.

Issuing and revoking keys

Issuing a key returns it once: Dinio stores only a hash of it and cannot show it again, so store it right away. Issuing a new key replaces the previous one of the same zone or user, which stops working immediately. Revoking a key leaves the zone or user without one.

# a new zone key — the response is {"api_key":"dz_…"}
curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/zones/example.com/api-key

# revoke it
curl -X DELETE -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/zones/example.com/api-key

# prints the new key once
dinio zone key create example.com
dinio zone key revoke example.com

const { api_key } = await dinio.zones.createApiKey('example.com'); // "dz_…"
await dinio.zones.revokeApiKey('example.com');

let key = client.zones().create_api_key("example.com").await?; // a Secret, "dz_…"
client.zones().revoke_api_key("example.com").await?;

A zone key can be issued by the zone key itself, the zone’s Owner and its Administrators. A personal key is issued on your user: see Your account.

Zones and users show whether a key exists in has_api_key; the key itself never appears in any other response.