Authentication#

By default the Kapkan API and dashboard are unauthenticated. This is safe only because the default api.listen value binds to 127.0.0.1 — the listener is reachable only from the host itself, so no token is required to read status, list attacks, or issue manual bans. The moment you bind the listener to a routable address, that protection disappears.

Setting a token#

The shorthand is a single operator token. Add token_env to the api block — it names the environment variable that holds the token; the secret itself is read from the process environment per request, never from the config file:

api:
  listen: "0.0.0.0:8080"
  token_env: "KAPKAN_API_TOKEN"   # token read from this env var, never the file

Then provide the value out of band, for example through your service manager's environment or a secrets file:

export KAPKAN_API_TOKEN="$(openssl rand -hex 32)"
./kapkan -config /etc/kapkan/config.yaml

Keeping the token in an environment variable rather than the YAML means the config remains safe to commit to git and diff alongside the rest of your configuration.

That single token is all most deployments need — the rest of this page (roles, tenants) is optional and can wait.

Roles#

For role-based access use tokens instead of token_env — a list where each entry names the env var holding its secret and a role:

api:
  listen: "0.0.0.0:8080"
  tokens:
    - { name: dashboard,  token_env: "KAPKAN_API_RO", role: viewer }
    - { name: automation, token_env: "KAPKAN_API_RW", role: operator }

name, token_env and role are all required for each entry; role must be exactly viewer, operator or agent. A missing or misspelled value is a hard validation error at startup, not a silent default.

There is no separate admin role to assign — an admin is simply an operator token with no tenant set. The role values the engine accepts are viewer, operator and agent; the admin/scoped distinction is the Multi-tenancy axis, covered below.

token_env and tokens are mutually exclusive — token_env is exactly one operator token. A request is matched against every configured token (in constant time); the highest matching role applies. A read with a viewer token works; a mutation with a viewer token is refused with 403 Forbidden; a request with no valid token is 401 Unauthorized. An empty or unset env var never matches, so a misconfigured secret fails closed.

Give every token a distinct secret — if one secret value is configured for two tokens with different roles or tenants, the request is refused (401 Unauthorized) rather than guessing which one you meant. The daemon logs ambiguous API token when this happens.

A token's secret value is read from the environment on every request, so rotating it takes effect on the next request. Adding or removing token entries in the YAML changes the token set, which takes effect on the next config reload. Neither needs a restart.

A token may also carry an optional tenant, scoping it to one customer's data. That is the Multi-tenancy feature, layered on the roles described here.

Manual ban/unban only require an operator token, but POST /api/v1/config/reload is additionally admin-only: the token must be unscoped (carry no tenant), because a reload rewrites every tenant's policy and the token set itself. A tenant-scoped operator token is refused with 403 Forbidden — config reload is restricted to unscoped (admin) tokens.

What it protects#

With a token set, every /api/v1 request must carry it in an Authorization header using the bearer scheme:

GET /api/v1/status HTTP/1.1
Host: kapkan.internal:8080
Authorization: Bearer <token>

The supplied token is compared to the configured one in constant time, so the comparison itself does not leak the secret through timing.

What stays open and what becomes protected:

The dashboard's static UI shell remains reachable so a browser can load it, but it has no data of its own: it polls /api/v1, so it prompts for the token and keeps it in sessionStorage. /metrics likewise stays open for your Prometheus scraper. See the dashboard page for how the UI handles the token prompt.

CSRF#

POST endpoints require Content-Type: application/json in addition to the token. A browser performing a cross-site request cannot set a custom Authorization header without a CORS preflight, and a simple form post cannot send the JSON content type. Requiring both — the token in a request header and the JSON content type — blocks cross-site request forgery against the manual ban, unban, and config-reload endpoints.

Related#

• Multi-tenancy — scope a token to one customer's data.
• Audit log — token names become the operator identity on every mutation.
• REST API — the endpoints the token protects.
• Dashboard — how the embedded UI prompts for and stores the token.
• Deployment — binding the listener and supplying the token in production.