Client identities

Part of DNS filtering. A client identity tells Dinio how to recognise one of your clients — a device or a network that uses Dinio as its resolver — so that sinkhole lists can be applied to it.

Identities belong to the user who creates them, not to a zone: these routes need a personal key, and a zone key gets 403 FORBIDDEN.

interface ClientIdentity {
  uuid: string;
  id_type: 'IP' | 'Hostname' | 'Path' | 'None';
  identify: string;
  name?: string;             // your label, 1–64 characters
  user_id: string;           // owner
  enabled: boolean;          // your switch; off = not applied
  suspended: boolean;        // suspended by Dinio
  owner_suspended: boolean;  // the owner's account is suspended
  created_at: number;
  updated_at: number;
}

id_type	Protocol	identify
IP	DNS over UDP/TCP	The client’s source IP address. You give it.
Hostname	DNS over TLS (DoT)	The label of the hostname the client connects to. Dinio generates it.
Path	DNS over HTTPS (DoH)	The part of the request path that identifies the client. Dinio generates it.
None	DNS over UDP/TCP	Same as IP.

identify is unique across the platform. A generated one is 16 characters of lowercase letters and digits 2–7, such as k3x7q2mzr5tvb4wa. It is not a secret — it travels in the clear and sits in every device’s configuration — but it can’t be guessed, and you can replace it at any time.

A suspended identity — suspended or owner_suspended — is not applied. You can read and delete it, but changing it and linking or unlinking lists is refused with 403 SUSPENDED.

List identities

GET /api/v1/client-identities

Your identities. Optional filters uuid and identify.

Get an identity

GET /api/v1/client-identities/:ref

:ref is the uuid or the identify value.

curl -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/client-identities/203.0.113.10

Create an identity

POST /api/v1/client-identities

Field	Type
id_type	string	IP, Hostname, Path or None.
identify	string	For IP and None only, and required there: an IP address. Leave it out for Hostname and Path (422 otherwise).
name	string	Optional label, 1–64 characters; doesn’t have to be unique.

# a DoH client: Dinio generates identify
curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"id_type":"Path","name":"phone"}' \
  https://api-dinio.bitelex.com/api/v1/client-identities

# an office network with a fixed address
curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" -H "Content-Type: application/json" \
  -d '{"id_type":"IP","identify":"203.0.113.10","name":"office"}' \
  https://api-dinio.bitelex.com/api/v1/client-identities

Returns 201 with the identity, including the generated identify. 409 if the IP address is already registered.

An identity counts against your package’s filter.clients.max: without a filter package the call is 403 NO_SUBSCRIPTION, at the limit 403 PLAN_LIMIT, and near it the response carries a PLAN_USAGE warning. See Packages and usage.

Change an identity

PATCH /api/v1/client-identities/:uuid

Field	Type
name	string | null	New label; null removes it.
enabled	boolean	Switch the identity off and on.
id_type	string	Change the type. Changing to Hostname or Path generates a new identify; changing to IP or None needs an identify.
identify	string	A new IP address, for IP and None only.

Replace the generated identify

POST /api/v1/client-identities/:uuid/identify

Generates a new identify for a Hostname or Path identity and returns the identity. The old value stops working at once, so reconfigure the client’s devices. 422 for an IP or None identity.

curl -X POST -H "Authorization: Bearer $DINIO_API_KEY" \
  https://api-dinio.bitelex.com/api/v1/client-identities/$IDENTITY_ID/identify

Delete an identity

DELETE /api/v1/client-identities/:uuid

409 while sinkhole lists are still linked to it — delete the links first.