--- title: Control Plane Auth --- # Control Plane Auth Control plane endpoints are used to manage workers, tokenizers, WASM modules, and other gateway operations. Configure admin authentication with JWT/OIDC and/or control-plane API keys.
#### Before you begin - Completed the [Getting Started](index.md) guide - Decide how admins authenticate (JWT, API key, or both)
--- ## Protected Control Plane Endpoints These routes are guarded by control-plane auth middleware when configured: - Worker management: `/workers`, `/workers/{worker_id}` - Tokenizer management: `/v1/tokenizers`, `/v1/tokenizers/{tokenizer_id}`, `/v1/tokenizers/{tokenizer_id}/status` - Parser admin endpoints: `/parse/function_call`, `/parse/reasoning` - WASM management: `/wasm`, `/wasm/{module_uuid}` - Cache flush: `/flush_cache` - Profiling: `/start_profile`, `/stop_profile` - Diagnostics of the gateway process: `/inflight`, `/heap_profile` - Deprecated load alias: `/get_loads` (the public `/loads` route it aliases needs no credential) - RL control plane: `/v1/rl/*`, mounted only with `--enable-rl` - Configuration view and key reload: `GET /config`, `POST /secrets/reload` — mounted only when control-plane auth is configured; see [Key files and rotation](#key-files-and-rotation) Control-plane middleware requires the **admin role** for every method on these routes but the read-only ones: a valid credential with the `user` role may `GET` and `HEAD` them, and gets `403` (`Admin role required for this control plane operation`) on any other method. The one read kept to the admin role is `GET /config`, whose view names what the user role's reads do not; it answers a `user` credential with the same `403`. A missing or invalid credential gets `401`. Control-plane credentials apply only to these routes. The inference routes, such as `/v1/chat/completions`, check the shared `--api-key` and per-tenant keys instead, and stay open when neither is set. Set `--api-key` as well to protect them. ### Admin Listener By default the control-plane routes answer on the gateway's data listener (`--port`), alongside the serving routes. Set `--admin-port` to serve them on an admin listener of their own instead: the whole list above moves there and the data listener answers `404` for them, so the control plane can sit on a private address behind its own network policy while the serving routes stay reachable. `--admin-host` sets the admin listener's bind address (the `--host` value by default; it needs `--admin-port`). The probe routes `/health`, `/liveness`, and `/readiness` answer on both listeners, so the admin listener can be probed on its own; the public `/loads` stays on the data listener. The split changes where the routes answer, not who may call them: control-plane authentication applies on the admin listener exactly as described on this page. When the gateway serves HTTPS, the admin listener presents the same certificate ([Configure TLS](tls.md#enable-server-tls)). The admin listener also sits outside the data listener's `--max-connections` bound, so it stays reachable while the data plane is saturated; `--admin-max-connections` gives it a bound of its own (`0`, the default, is no bound). Each listener needs its own port; see the [Listeners reference](../reference/configuration.md#listeners). ### Without Control Plane Auth When no control-plane API keys and no JWT settings are configured, the routes above fall back to the shared `--api-key`: | Keys configured | Control plane routes | |-----------------|----------------------| | `--api-key` (with or without tenant keys) | Need `Authorization: Bearer `; per-tenant keys get `401` | | `--tenant-api-key` only | Every request gets `401` | | None | Open to anyone | This fallback is for a gateway where control-plane auth is not configured at all. The gated `GET /config` and `POST /secrets/reload` never take part in it: without control-plane auth they are not mounted and answer `404` on every listener. For what happens when configured JWT auth fails to initialize at startup, see [Option B: JWT / OIDC](#option-b-jwt-oidc). #### Default posture With no key configured at all, which is what the quick-start commands and the Kubernetes recipe give you, the gateway is open: anything that can reach it can list the backends with their addresses (`GET /workers`, `GET /get_loads`), register or remove backends by URL (`POST /workers`, `PUT`/`PATCH`/`DELETE /workers/{id}`), drop the engines' prefix caches (`POST /flush_cache`), start and stop the engines' profilers (`POST /start_profile`, `POST /stop_profile`), write the gateway's own heap profile to disk (`POST /heap_profile`), manage parsers, WASM modules and tokenizers, and send inference requests. Two read-only routes are public in every configuration and name each backend by its address as well: `GET /loads` (the backends' live loads) and `GET /engine_metrics` (the engines' own metrics). The metrics listener (`--prometheus-port`, `29000` by default, bound to `0.0.0.0`, or to `::` when `--host` is an IPv6 address) has no authentication in any configuration and names each backend by its address in its per-worker series. SMG keeps this default so a local start stays one command, but it says so: when a plane is open, the first log lines carry one `WARN` record whose message starts with `SECURITY POSTURE: this gateway runs without authentication`, with a field per open surface (`control_plane`, `data_plane`, and `metrics_listener` with its bound address) naming the routes and the flag that closes them. It is silent once both planes are keyed, with one exception: a router whose [high-availability mesh](../concepts/architecture/high-availability.md#mesh-mtls) listener runs without TLS still logs the record, whose `control_plane` field names that listener's address and the `--mesh-tls-ca-cert`, `--mesh-tls-cert`, and `--mesh-tls-key` flags that close it. To close the open surfaces: | Surface | Flag | |---------|------| | Control plane routes (the list above) | `--control-plane-api-keys id:name:admin:` (or a key file, `--control-plane-api-keys-file`), or `--jwt-issuer` with `--jwt-audience`; the shared `--api-key` also gates them. `--admin-port` moves them to their own [admin listener](#admin-listener) that a network policy can fence | | Serving routes (`/v1/chat/completions` and the rest) | `--api-key `, or `--tenant-api-key tenant:` per tenant | | Metrics listener | No credential exists: bind it to a private address with `--prometheus-host` and fence the port with a network policy ([Monitoring](monitoring.md#enable-metrics)) | | Public read-only routes (`GET /loads`, `GET /engine_metrics`, `/v1/models`, `/get_server_info`, `/get_model_info` and the health routes) | No credential exists: fence the gateway's port with a network policy | In Kubernetes, a gateway that discovers its workers never needs `POST /workers` from outside, so there is no reason to leave the control plane open there: set control-plane keys, and restrict the gateway's ports with a NetworkPolicy to the clients and the scraper that need them. --- ## Option A: API keys ```bash smg launch \ --worker-urls http://worker:8000 \ --control-plane-api-keys 'admin1:PlatformAdmin:admin:super-secret-key' ``` Use the key in `Authorization` header: ```bash curl -H "Authorization: Bearer super-secret-key" \ http://localhost:30000/v1/tokenizers ``` Format: `id:name:role:key` where role is `admin` or `user`. Repeat the flag to add more keys, or put them in a file or the environment instead ([Key files and rotation](#key-files-and-rotation)). A `user` key reaches the read-only routes (`GET` and `HEAD`, except the admin-only `GET /config`); every other control-plane method answers it with `403`. SMG refuses to start on a malformed entry, including one with a role other than `admin` or `user`; the error does not echo the entry, since it carries the key. --- ## Option B: JWT / OIDC ```bash smg launch \ --worker-urls http://worker:8000 \ --jwt-issuer https://login.example.com \ --jwt-audience api://smg-control-plane \ --jwt-role-mapping 'Gateway.Admin=admin' \ --jwt-role-mapping 'Gateway.User=user' ``` `--jwt-issuer` and `--jwt-audience` are required together: SMG refuses to start with only one of them. It also refuses to start on a malformed `--jwt-role-mapping` entry (one without `=`, or with a gateway role other than `admin` or `user`). SMG checks the token's signature (RS256, RS384, RS512, ES256, or ES384, with the JWKS key named by the token's `kid`), issuer, audience, expiry, and not-before (`nbf`). The expiry and not-before checks share a 30-second clock-skew leeway, and a token without an `nbf` claim passes the not-before check. SMG then assigns a role: - The role comes from the claim named by `--jwt-role-claim` (default `roles`). Only when that claim is missing does SMG read the `role`, `roles`, `groups`, and `group` claims. - Without `--jwt-role-mapping`, a claim value of `admin` or `user` (in any case) is used as the role. - With mappings, only mapped values count. A token with no mapped value gets the `user` role: it may `GET` and `HEAD` control-plane routes (except the admin-only `GET /config`), and any other method answers it with `403`. Optional explicit JWKS URI: ```bash --jwt-jwks-uri https://login.example.com/.well-known/jwks.json ``` Without it, SMG reads `/.well-known/openid-configuration` at startup to find the JWKS URI. The discovery URL and the JWKS URI must use `https://`; plain `http://` is accepted only for `localhost`, `127.0.0.1`, and `::1`. An `https://` URL is also rejected when its host is a private, loopback, or link-local IP address, or a name ending in `.internal` or `.local`, such as an in-cluster `*.svc.cluster.local` service. When JWT validation cannot be set up at startup — the URL is rejected, or discovery fails — control-plane authentication stays required: SMG logs `Failed to initialize JWT authentication: ` and keeps running without JWT validation. The configured control-plane API keys keep working, whether they came from the flag, the environment, or a key file; JWTs and every other token get `401`. SMG does not retry JWT initialization while running, so restart the gateway after correcting the configuration or restoring the identity provider. JWTs are validated first when configured. A token with three dot-separated parts that fails JWT validation gets `401`; SMG does not fall back to API key validation for it. Any other token is checked against the control-plane API keys. --- ## Option C: JWT + API keys together ```bash smg launch \ --worker-urls http://worker:8000 \ --jwt-issuer https://login.example.com \ --jwt-audience api://smg-control-plane \ --control-plane-api-keys 'admin1:PlatformAdmin:admin:super-secret-key' ``` This lets human admins use OIDC while service automation uses API keys. --- ## Key files and rotation Each key flag has a file counterpart, for a key mounted as a secret: `--api-key-file` (the shared key alone on one line, surrounding whitespace dropped), `--tenant-api-keys-file` (one `tenant_id:key` per line), and `--control-plane-api-keys-file` (one `id:name:role:key` per line); blank lines and lines starting with `#` are skipped. Each key can also come from the environment: `SMG_API_KEY`, `SMG_TENANT_API_KEYS`, and `CONTROL_PLANE_API_KEYS` take the values, and the `*_FILE` names of each take the file path. The flag beats the environment, and SMG refuses to start when both a value and a file are given for the same key. A keyed start logs one INFO record naming where each secret came from: `flag`, `env`, or `file` under the Rust binary, and under the Python launcher `launcher` for a key given as a flag or environment value (the launcher resolves it and hands the gateway the value) or `file` for a key file. No value is ever logged. Keys that came from a file can be rotated without a restart: - `POST /secrets/reload` (admin role) reads the key files again by the start's rules and puts each set in force as one swap; a key given on the command line or in the environment stays as the start read it. The route answers `200` with the files read and whether each set changed, `409` when no key came from a file, and `422` when a file cannot be used — unreadable, unparsable, or failing the start's checks — leaving every set as it was; the error names the setting and the path, never the content. - `--secrets-auto-reload` watches the key files and puts a changed file's keys in force as the reload route does, so a mounted secret rotated in place takes effect on its own. It is off by default, and a start with no key file warns that there is nothing to watch. `GET /config` answers the effective configuration with every secret redacted and the keys in force named by fingerprint; it is the one read that requires the admin role. `/config` and `/secrets/reload` exist only when control-plane auth is configured — without it they answer `404` — and a startup INFO record (`GATED CONTROL-PLANE ROUTES`) says whether they are mounted. --- ## Audit logging With control-plane auth configured, SMG can audit control-plane requests as INFO lines on the `smg::audit` log target. Every request it authenticates, denies, or rejects gets an admission line with the message `control_plane_audit`. An admitted request other than a `GET` or `HEAD` also gets an outcome line, `control_plane_mutation`, once its handler has answered: it carries the handler's HTTP status and, when the handler named one, the resource it acted on, such as a worker, tokenizer, or WASM-module ID. The two lines share a `request_id`. See [Audit Log Format](../concepts/security/authentication.md#audit-log-format) for the full field list. Whether SMG writes these lines by default depends on how you run it: === "Cargo binary" The `smg` binary from `cargo install` or a source build logs audit events by default. Turn them off with `--disable-audit-logging`: ```bash smg launch \ --worker-urls http://worker:8000 \ --control-plane-api-keys 'admin1:PlatformAdmin:admin:super-secret-key' \ --disable-audit-logging ``` === "pip or Docker" The Python launcher behind `pip install smg` and the container image leaves audit logging off. Turn it on with `--control-plane-audit-enabled` (this launcher has no `--disable-audit-logging`): ```bash smg launch \ --worker-urls http://worker:8000 \ --control-plane-api-keys 'admin1:PlatformAdmin:admin:super-secret-key' \ --control-plane-audit-enabled ``` See [Python Launcher Differences](../reference/configuration.md#python-launcher-differences) for the other flags that differ between the two. --- ## Next Steps - [Admin API Reference](../reference/api/admin.md) - [Configuration Reference](../reference/configuration.md#control-plane-authentication)