Deevnet API

API Reference

Mon, 01 Jan 0001 00:00:00 +0000

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication #

Every /v1 request carries Authorization: Bearer <token>. A request without a token the API recognizes answers 401 with WWW-Authenticate: Bearer realm="deevnet-api". The three service routes, /healthz, /readyz and /version, take no token.

Tokens #

The token is one of four things, and it decides what the caller may do.

Token	What it is	May
Operator	the site’s operator token	everything
Tenant	`dvt1.<tenant>.<nonce>.<mac>`, returned when the tenant is created	read and delete its own tenant, restore itself, and manage its own workloads, names, devices, keys, accounts and certificates
Enrollment	single-use, issued by an admission	create the one tenant it was issued for, once
Egress agent	the exit node’s token	read `GET /v1/fabric/egress`, nothing else

A tenant holds exactly one of these at a time: the enrollment token for its first apply, then its own token for every later one.

Tenant Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Tenant lifecycle #

A tenant is admitted by the operator, then creates itself. Everything after admission is the tenant’s own call, made with its own token ( ADR-0015).

Admission #

POST /v1/admissions reserves a name and issues a single-use enrollment token. Only the operator may call it, and the operator hands the token to the tenant over a channel trusted with a password.

At a site with a tenant developer network, the answer also carries a Wi-Fi key ( ADR-0029). The tenant needs that network to reach the API at all, so the key cannot come from the tenant’s own apply.

Device Services

Mon, 01 Jan 0001 00:00:00 +0000

Device services #

A tenant’s devices get four things from the API: a registry entry, a fixed address, a Wi-Fi key and a broker account. Each is its own resource, and none implies another. The API Reference has every field; this page is what the fields do not say.

Registry #

A registry entry is identity, not authorization. Registering a device grants it nothing. What a device may consume is carried by a credential it proves ( ADR-0020 §2), and this resource issues none. Nor does a device reach its tenant’s network.

Service Certificates

Mon, 01 Jan 0001 00:00:00 +0000

Service certificates #

A tenant’s own service gets a server certificate from the API, for a name in the tenant’s own zone, and the tenant keeps the key. The site’s Tenant Service CA signs it ( ADR-0037). It chains to the Deevnet Root CA, which every client on a site already trusts. The API Reference has every field; this page is what the fields do not say.

The key #

The private key never reaches the API. A tenant makes it, keeps it, and sends a signing request made with it. The certificate comes back; the key was never sent.

Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Conventions #

Every route follows the same few rules. They are what make a failed or repeated call safe.

Ensures #

Every create is an ensure. Calling it again for the same name converges on the same object: the identity stays, an issued secret is kept, and only what the caller may change is taken. An object that already exists on a backend is adopted and corrected.

This is what makes a retry safe, and it is why a tenant’s Terraform can re-apply after any failure.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration #

The service is configured by environment variables only. The container has no configuration file. Values below are illustrative; a site’s own come from its automation.

Core #

Two variables are required, and the service refuses to start without them.

Variable	Required	Meaning
`DEEVNET_API_TOKEN`	yes	the operator bearer token for `/v1`
`DATABASE_URL`	yes	PostgreSQL connection string. The schema is migrated on start
`DEEVNET_AGENT_TOKEN`	no	the exit node’s egress agent. It reads `GET /v1/fabric/egress` and nothing else
`DEEVNET_API_LISTEN`	no	listen address, default `:8080`
`DEEVNET_API_TLS_CERT`, `DEEVNET_API_TLS_KEY`	no	serve TLS, 1.2 at the least. Set both or neither

With only these set, the service runs and every tenant route answers 501.

Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

Release Notes #

Every release of the Deevnet API, newest first. Versions are MAJOR.MINOR.PATCH; until 1.0 a minor release may change behavior or configuration, and the notes say so under Upgrading.

One tag covers everything this repository builds: the API, the two writers (deevnet-broker-account, deevnet-log-user) and deevnet-kit.

0.12.0 (2026-10-18) #

Added #

Extra names and addresses on a Pi’s server certificate (deevnet-kit, CHG-0050). A Pi with names in a site’s DNS, or about to move to a network where it will have another address, can have its certificate carry them first. names= in deevnet-kit.txt sets them on first boot; deevnet-kit names [list | set | add | rm] changes them later, and regen-certs applies them. They are kept in /etc/deevnet-kit/names, one a line. Wildcards are refused.

Changed #

deevnet-kit regen-certs restarts Grafana as well as the broker and vmauth. Grafana presents the same certificate on 3000 and kept the old one until it was restarted.

Upgrading #

Nothing changes for a card that sets no names. A card initialized on 0.11.0 or earlier can be given names with deevnet-kit names set and regen-certs; no reflash.

0.11.0 (2026-10-11) #

Added #

Server certificates for tenants’ own services (ADR-0037, CHG-0047): PUT, GET and DELETE /v1/tenants/{name}/certificates/{certificate}, and GET of the list. A tenant sends a signing request for a label in its own zone; the site’s Tenant Service CA, in OpenBao, signs a one-year server certificate, and it comes back with the chain a server presents. The request is read for its public key alone. Asking again returns the same certificate until sixty days before it expires. Nothing is revoked, and nothing renews by itself.
A documentation site, https://deevnet.github.io/deevnet-provisioning-api/, with the API reference rendered from api/openapi.yaml.
api/openapi.yaml, an OpenAPI 3.1 specification, as the contract. It replaces docs/api-v1.md, and tests fail when it and the code disagree on a route or a wire field.

Upgrading #

Certificates are off until OPENBAO_TENANT_SERVICE_MOUNT names the Tenant Service CA’s mount. A site without one needs to change nothing. A site with one adds the variable, and update on <mount>/sign/tenant-service to the service’s OpenBao policy.
The database gains a table, tenant_certificates, by migration 0010. It runs at start.

0.10.0 (2026-10-06) #

Added #

Fixed addresses for tenants’ devices (ADR-0035, CHG-0044): POST, GET and DELETE /v1/tenants/{name}/devices/{device}/address. The API allocates an address from the range a site sets aside, reserves it on the DHCP server for the device’s MAC, and publishes the device’s name in the tenant’s zone. A reconcile puts reservations back.
deevnet-kit exports the Pi’s certificate authority as deevnet-kit-ca.pem (CHG-0031).

Changed #

Backend TLS is verified by default. PROXMOX_INSECURE_TLS, OPNSENSE_INSECURE_TLS and OMADA_INSECURE_TLS now default to false.

Upgrading #

A backend still serving a self-signed certificate must be named. Set its *_INSECURE_TLS variable to true, or the API fails to reach it.
Fixed addresses are off until configured. Set DEEVNET_IOT_ADDRESS_RANGES to turn them on.

0.9.1 (2026-09-27) #

Changed #

A workload no longer runs a package upgrade on first boot, so it is reachable sooner and its packages are what the template carried.

0.9.0 (2026-09-27) #

Added #

A tenant’s ssh_keys reach its workloads, and the workload reports the account they landed on as login_user (CHG-0028).
Admission issues a Wi-Fi key for the tenant developer network (CHG-0029), in the trust class DEEVNET_ADMISSION_WIFI_CLASS names. DELETE /v1/admissions/{name} revokes the key of an admission never used.
A Wi-Fi key may bind to one client with mac (CHG-0029).
The state store’s admin client can use TLS, verified against the site’s certificate authority: MINIO_ADMIN_TLS and MINIO_ADMIN_CACERT (CHG-0030).
deevnet-kit writes the app’s broker login to kit.env, and sets the Pi’s host name and Wi-Fi at first boot.

Changed #

Deleting a tenant removes its broker accounts with it (CHG-0028).

0.8.1 (2026-09-24) #

Added #

deevnet-kit selftest, and a starter dashboard on the take-home Pi.

0.8.0 (2026-09-24) #

Added #

A dashboard organization per tenant (ADR-0024, CHG-0024). Creating a tenant creates its organization, an Editor login and three log data sources with fixed UIDs, and returns the login in dashboard. The password is also returned on a reconcile.
deevnet-kit, the API’s stand-in on a take-home Raspberry Pi.

0.7.0 (2026-09-22) #

Changed #

The log topic level is reserved for devices’ own logs (ADR-0027 §3). A device account may publish only log/<its own device>; a workload account may subscribe under log/ and not publish there.

Upgrading #

A broker account whose patterns reach into log/ in a way this forbids is refused the next time it is applied.

0.6.0 (2026-09-22) #

Added #

Log store tokens for each tenant (CHG-0020): an ingest token and a read token, returned in log on create and on reconcile, with the tenant’s partition family in account_id.
deevnet-log-user, the writer that maintains the log store’s users.

0.5.1 (2026-09-20) #

Fixed #

The broker account writer’s connection pins the host key’s algorithm as well as the key, so it no longer fails against a host that offers several.

0.5.0 (2026-09-20) #

Added #

Broker accounts (CHG-0016): POST, GET and DELETE /v1/tenants/{name}/broker-accounts. The API issues a tenant’s MQTT accounts, writes the tenant prefix onto every topic pattern, and keeps only a hash of the password.
deevnet-broker-account, the writer that puts an account into the broker’s database.

0.4.0 (2026-09-20) #

Added #

The device registry: POST, GET and DELETE /v1/tenants/{name}/devices. An entry is a device’s identity and grants it nothing.

0.3.1 (2026-09-18) #

Fixed #

Revoking a tenant’s last Wi-Fi key no longer fails. The wireless controller refuses an empty key profile, so the API leaves one unusable placeholder entry in it.

0.3.0 (2026-09-18) #

Added #

Wi-Fi keys: POST, GET and DELETE /v1/tenants/{name}/wifi-keys. One key per tenant per trust class; the API chooses the password and takes the SSID and VLAN from the class.

0.2.6 (2026-09-17) #

Changed #

A workload is given a recursive resolver, not the authoritative tenant DNS server.

Upgrading #

DEEVNET_WORKLOAD_RESOLVER is a new required site variable.

0.2.5 (2026-09-17) #

Added #

secrets_stored on a tenant read: whether the API can still read the secrets it holds.

0.2.4 (2026-09-17) #

Fixed #

A stored secret that can no longer be opened loses that secret, not the whole tenant: the tenant still reads, and supplies the secret again.

0.2.3 (2026-09-17) #

Changed #

The audit log names the caller, and changes to published names are audited.

0.2.2 (2026-09-17) #

Fixed #

A tenant whose registry row is gone is answered 404, not 401, so its provider restores it.

0.2.1 (2026-09-17) #

Fixed #

A name published beside a workload no longer takes over the workload’s reverse record.

0.2.0 (2026-09-17) #

Added #

Tenants: create, restore, resume, read, reconcile and delete, with index allocation against the registry and the fabric (ADR-0015).
Admission and tenant tokens: POST /v1/admissions issues a single-use enrollment token, and a tenant’s own token verifies without the registry (ADR-0015 §10).
Workloads and published names: /v1/tenants/{name}/workloads and /records (ADR-0015 §11–§13).
Secrets from OpenBao, sealing of stored tenant secrets, and TLS (ADR-0016).
An agent token that reads GET /v1/fabric/egress and nothing else (ADR-0015 §7).

0.1.0 (2026-09-14) #

The first tagged release.