API & OpenAPI docs

Everything the admin UI does, it does over Taranac’s own REST API — the web interface is just a client. That API is fully described by an OpenAPI schema generated from the code itself, and the platform can serve that schema as interactive documentation: Swagger UI, Redoc and the raw openapi.json.

That documentation surface is off by default. It is a single environment flag away, and this page explains what you get when you turn it on, why you probably should not leave it on in production, and where to browse it without installing anything.

The quickest way to see the API is the public demo instance, which runs with the docs surface enabled on purpose:

• demo.taranac.pro/docs — Swagger UI
• demo.taranac.pro/redoc — Redoc, with the tags nested into collapsible domain groups
• demo.taranac.pro/openapi.json — the raw schema, for generating a client

The demo runs the same images as your install, so what you read there is what your instance exposes.

Note that all three are mounted at the application root, not under /api/. The bundled edge (the edge container) already proxies them; a third-party reverse proxy in front of Taranac that only forwards /api/* will not reach them.

DOCS_ENABLED lives in the .env file in your deployment bundle directory and defaults to false:

DOCS_ENABLED=false  # Swagger/Redoc/openapi.json — keep off in production

Set it to true and recreate the api container so it picks the new value up:

./taranac up -d      # recreates containers whose env changed

To turn it back off, set it to false and run ./taranac up -d again. When the flag is off, FastAPI is built with no documentation URLs at all: the three routes 404, and the schema is never even generated.

When the flag is on, admins get an API item in the sidebar’s Advanced section that opens /docs in a new tab. The UI reads the flag from the backend (it is carried on /auth/me as docs_enabled), so the link can never point at a disabled endpoint — no flag, no link.

The schema is not raw FastAPI output — the tag taxonomy, the per-tag descriptions and the Markdown overview at the top are maintained in the product as a first-class surface, and CI fails if a route carries a tag that is not described. The conventions it documents are the same ones the whole API follows:

Tags are grouped by domain — Authentication & Access, Identity, Network, AAA · TACACS+, AAA · RADIUS, AAA · Policy & Logs, NAC, NAC · PKI, Configuration Tracker, Monitoring & Ops, System Settings, Reports, System — which is the fastest way to find the endpoints behind a screen you are looking at in the UI.

Not everything that talks to this API logs in. These surfaces are described in the same schema, and they are worth knowing before you write a client — or point a scanner at an instance and wonder why something answered:

Devices use one URL, the EST gateway’s: https://<host>:8445/.well-known/est, the est-gateway container on port 8445 (EST_GATEWAY_PORT), which verifies the client certificate itself. It serves the reads, the first enrollment by password and renewal. The console’s HTTPS port (443) also serves the reads and simpleenroll, like the rest of the API, but a renewal (simplereenroll) there is always refused.

The gateway passes what it verified to the API as headers — X-SSL-Client-Verify, X-SSL-Client-S-DN, X-SSL-Client-Cert — and proves they are its own with X-Est-Proxy-Key, which must match EST_PROXY_KEY from .env (the installer generates it). The mTLS proxy secret setting (nac.est_mtls_proxy_secret) is a second accepted key, only for a client-certificate terminator of your own. Both are compared in constant time. With neither set, the API ignores those headers outright. The frontend vhost on 443 blanks all of them on every inbound request, so a client cannot smuggle its own.

A refused simpleenroll answers 401 with WWW-Authenticate: Basic realm="EST", so a client that sent no password retries with one. EST switched off, or a bad CSR, is 422. Every refusal is recorded in the audit log. The full flow, with the approval endpoints, is on EST enrollment.

The TACACS+ TLS and NAC (EAP) server certificates have the same endpoints under /api/v1/tacacs/server-cert and /api/v1/nac/server-cert: read the current one, /issue from an Internal CA (san_dns and san_ip, up to 20 each), /upload, /self-signed, /deploy and /expiry; GET …/issue-defaults returns what the issue form is prefilled with (the node’s name and addresses, the Default CA), and POST …/restore-previous makes the most recently deployed earlier certificate active again and deploys it. There is no CSR endpoint. For an external CA, generate the key and the CSR outside Taranac, have the CA sign it, then POST …/server-cert/upload the certificate and key.

PATCH /api/v1/tacacs/settings carries no certificate fields. Unlike most request bodies, this settings document does not reject a field it does not know, so a client that still sends tls_cert, tls_key or tls_ca gets no error, and the values do nothing. See TACACS+ over TLS.

The PKI endpoints behind Taranac under your corporate root, all under /api/v1/nac/pki; reads need nac_pki.view, changes nac_pki.edit:

An Internal CA’s certificate field takes exactly one certificate; a request with several is refused with their count, and the issuing chain goes in its own field. The EST and SCEP endpoints, the challenge password and the enrollment-guard blocks are listed on EST and SCEP.

• CLI & scripts — the ./taranac wrapper and the .env file this flag lives in
• Settings reference — the runtime settings surface, edited in the UI rather than in .env
• RBAC — the permissions that gate every endpoint
• Versioning & releases — what a version covers, and what that means for API stability