Authentication#
The server supports one bearer token for the server API and a separate token for the admin API. This supports service-to-service authentication.
Warning
Bearer tokens travel in plain text. Use TLS at the reverse proxy or platform edge whenever a token crosses a network.
API Authentication#
Supply the token through the VLC_API_KEY environment variable or --api-key. With the variable set, start the server normally:
$ vl-convert serve --port 3000
Conversion, theme, font, bundling, and API documentation routes now require this header:
Authorization: Bearer <key>
For example:
$ curl http://127.0.0.1:3000/themes \
> -H "Authorization: Bearer $VLC_API_KEY"
A missing or incorrect token returns 401 Unauthorized with a WWW-Authenticate: Bearer header. The body is {"error":"unauthorized"}, or empty when --opaque-errors is set.
The token grants access to every protected route in the server API. It does not restrict which external resources a specification can load. Configure data, font, plugin, and resource policies separately.
Unauthenticated Health Routes#
/healthz, /readyz, and /infoz never require a token, so load balancers and process supervisors can reach them.
/infoz reports component versions and the local timezone. If those host details should stay private, expose only /healthz and /readyz through a public reverse proxy.
Admin API Authentication#
The admin API is optional and independent of the server API. Set VLC_ADMIN_API_KEY, then enable the admin API:
$ vl-convert serve \
> --admin-host 127.0.0.1 \
> --admin-port 3001
$ curl http://127.0.0.1:3001/admin/diagnostics/workers \
> -H "Authorization: Bearer $VLC_ADMIN_API_KEY"
The server API token does not grant admin API access, and the admin API token does not grant server API access.
The admin API requires a key when bound to a non-loopback TCP address. It can run without a key on loopback or a Unix domain socket, where network access or filesystem permissions can restrict who can connect.
See Deploying the Server for a Unix socket example and Admin Server API for the management operations.