Configuration
API tokens
kbs_ service tokens and kbk_ API keys — how to create them, what scopes and cluster lists they carry, and why a service token is rejected when it arrives from the internet.
On this page
REST API tokens authenticate non-interactive callers against /api/v1/*
without a user session. Create and revoke them at Administration → API
Tokens (/admin/api-tokens, Admin role).
They are not the same thing as the ingest tokens the agent and
Falco use. Those start with kb_, live in a separate store, and
are issued from Administration → Agents & Ingest → Agent Tokens. The two
stores never cross: an ingest token can never authenticate a REST call, and a
REST token can never authenticate the agent channel. That isolation is itself a
security property.
Two kinds
kbs_ service token | kbk_ API key | |
|---|---|---|
| For | Internal machine callers that reach the API directly (backend-to-backend, inside your network) | Your own integrations, CI/CD and MCP hosts |
| Who may create it | An Admin. Not available to organizations on KubeBolt Cloud | An Admin (on Cloud, with a verified email) |
| Role | editor unless the request names another | Picked in the form (viewer preselected). Over the API, editor when omitted |
| Default scopes | The service set (below) | None — you pick |
| Cluster list | None — reads every cluster | Optional (below) |
| Through the public edge | Rejected | Works |
Both are stored as SHA-256 hashes. The plaintext — the prefix followed by 32
random characters — is returned exactly once, at creation, and is never
recoverable; copy it then. The list keeps only a display prefix (kbk_ plus
the first 8 characters).
Both accept an optional expiry. Leave it empty for no expiry; revoking is immediate either way.
Creating one
In the UI, choose New API token (or New service token), give it a Label and, for an API key, a Role, its Scopes, its Clusters and an optional Expires after (days). The token is shown once in the next dialog.
Or call the endpoint with an admin session. type is service or apikey
(default service), ttlHours of 0 or omitted means no expiry, and
clusters takes cluster ids — see Cluster targeting:
# an admin session token (API tokens cannot create tokens)
ADMIN_TOKEN=$(curl -s -X POST https://kubebolt.example.com/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"…"}' | jq -r .accessToken)
curl -X POST https://kubebolt.example.com/api/v1/admin/api-tokens \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{
"label": "ci-readonly",
"type": "apikey",
"role": "viewer",
"scopes": ["/api/v1/resources", "/api/v1/insights"],
"ttlHours": 720
}'
The 201 response carries the plaintext once, plus the token’s metadata:
{
"token": "kbk_…",
"apiToken": {
"id": "6f1c…", "prefix": "kbk_ab12cd34", "label": "ci-readonly",
"type": "apikey", "role": "viewer",
"scopes": ["/api/v1/resources", "/api/v1/insights"],
"createdAt": "…", "createdBy": "…", "expiresAt": "…"
}
}
Every issue, cluster-list change and revoke lands in the admin audit trail
(GET /api/v1/admin/actions) with the label, type, role, scopes and clusters —
never the token — enough for a reviewer to judge whether the grant was
appropriate.
Using one
Send it as a bearer token, exactly like a session token:
curl -H "Authorization: Bearer $KUBEBOLT_TOKEN" \
"https://kubebolt.example.com/api/v1/resources/deployments?namespace=shop"
Unknown, revoked and expired tokens — and a service token arriving over the
public edge — all get
401 {"error":"invalid or expired token"}. A path outside the token’s scopes,
or above its role, gets 403. The
REST API reference lists every route with the role it needs.
Scopes
A scope is a URL path prefix. A token may call a path when any of its
scopes is a prefix of it — /api/v1/resources covers
/api/v1/resources/deployments/shop/checkout/scale. * grants every
authenticated route. An empty scope set denies everything — the check
fails closed.
Scopes stack on top of the role, they do not replace it: a viewer token
scoped to * still cannot write.
A service token created without explicit scopes gets the service set:
/api/v1/cluster/overview
/api/v1/insights
/api/v1/events
/api/v1/resources
/api/v1/mcp
The form’s presets for API keys are Cluster overview, Resources,
Insights, Events and Metrics (/api/v1/metrics), plus two
whole-surface options: MCP only (read-only tools), which collapses to
/api/v1/mcp and nothing else, and Everything (all authenticated paths),
which collapses to *.
MCP only is the one to reach for when a host only needs to read. It pins
the token’s role to viewer on the server, whatever the creating request asks
for, and defaults to 90 days of expiry. Before 2.2 the only way to reach the
MCP server from the form was Everything, which handed the whole API to a
key that needed read-only tools; if you set an MCP host up that way, replace
its key.
No API token can reach /api/v1/admin/api-tokens, whatever its scopes say.
Credentials are created, edited and revoked by a signed-in admin, so a leaked
token cannot mint itself a broader one.
Cluster targeting
An API key reads every cluster of its organization, or only the ones ticked for it (Every cluster in the organization / Only these clusters). The list is set at creation and edited afterwards from the pencil on the token’s row. Over the API:
curl -X PATCH https://kubebolt.example.com/api/v1/admin/api-tokens/$TOKEN_ID/clusters \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-d '{"clusters": ["3f9a2c1e-…"]}'
The list holds cluster ids — the clusterId field of
GET /api/v1/clusters, which is the cluster’s kube-system namespace UID. An
empty list means every cluster, including ones added later. A kubeconfig
context that hasn’t reported its id yet can’t be picked. Service tokens carry
no list and are refused (400). A change takes effect on the token’s next
request; the token itself does not change.
The list is checked on every read path: the cluster a request names, the
cluster a request that names none falls back to, everything scoped per
cluster — findings, runtime events, insight history, bursts, mutes, the shift
report, the fleet PromQL path — and the cluster lists themselves, so
GET /api/v1/clusters and Kobi’s list_clusters name only what the token may
read.
A key limited to some clusters is also kept out of organization-wide
administration, whatever its scopes and role: /api/v1/admin/…,
/api/v1/users, /api/v1/teams and /api/v1/account answer 403, and so
does any write under /api/v1/clusters.
Within its list, a caller picks the cluster per request:
curl -H "Authorization: Bearer $TOKEN" \
-H "X-KubeBolt-Cluster: prod-eu-west" \
https://kubebolt.example.com/api/v1/cluster/overview
The header value is the cluster’s context as returned by
GET /api/v1/clusters (agent: followed by the cluster id for an
agent-connected cluster). A cluster
outside the list gets 403 you do not have access to this cluster. Omit the
header and you get the cluster currently selected in KubeBolt — or, for a key
limited to some clusters, the first one it may read when the selected cluster
isn’t on its list.
The public-edge restriction
A kbs_ service token presented over the public edge is rejected, even
when it is otherwise valid.
The bundled nginx force-sets X-KubeBolt-Edge: public on everything it
proxies — /api/, the WebSocket routes, and the port-forward proxy — using
proxy_set_header, which overrides whatever the client sent. The chart’s
Gateway API route (gatewayAPI.enabled) sets it the same way. The API rejects
service tokens carrying that header, so a leaked kbs_ token is useless from
the internet.
Two things follow, and both are easy to trip over:
- It only holds if the API is unreachable except through the proxy. The
control assumes the
apiService is ClusterIP-only. Expose the API directly — a LoadBalancer, an Ingress that bypasses the bundled web container — and the header is never set, so the protection is gone. Keep it internal. - Internal callers are unaffected. A caller reaching the API Service in-cluster never carries the header. Neither does the single-container image, which has no nginx — so don’t publish one to the internet with service tokens issued.
On KubeBolt Cloud, https://api.kubebolt.io is a public edge: use an API key.
What this means for MCP over HTTP
Kobi’s read-only MCP server is
POST /api/v1/mcp, and it is API-token authenticated. Which token you need
depends on where the client runs:
- Inside the network — a CI job in the same cluster, an agent calling the
API Service directly. A
kbs_service token works, and its default scopes already include/api/v1/mcp. - Through the UI URL — Claude Code on a laptop, a hosted agent, anything
that goes through the bundled nginx, and anything on KubeBolt Cloud. A
service token will be rejected at the edge. Use a
kbk_API key created with MCP only, which is exactly this case:/api/v1/mcpas its whole surface andvieweras its role. Tick the clusters it may read while you are in the dialog. Read-only is enforced server-side too, from the tool catalogue, so a client cannot invoke a mutating tool even by name.
Send X-KubeBolt-Cluster alongside it to target a specific cluster.
Revoking
Delete the token in the UI — you confirm by typing its label — or call
DELETE /api/v1/admin/api-tokens/{id}. Revocation takes effect on the next
request; there is no cached grant to wait out. Revoked and expired tokens stay
in the list with their status, next to each token’s prefix, label, role,
scopes, clusters, Last used and Expires, so an unused token is easy to
spot and retire.