KubeBolt docs
ENES GitHub

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
  1. Two kinds
  2. Creating one
  3. Using one
  4. Scopes
  5. Cluster targeting
  6. The public-edge restriction
  7. Revoking

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 tokenkbk_ API key
ForInternal machine callers that reach the API directly (backend-to-backend, inside your network)Your own integrations, CI/CD and MCP hosts
Who may create itAn Admin. Not available to organizations on KubeBolt CloudAn Admin (on Cloud, with a verified email)
Roleeditor unless the request names anotherPicked in the form (viewer preselected). Over the API, editor when omitted
Default scopesThe service set (below)None — you pick
Cluster listNone — reads every clusterOptional (below)
Through the public edgeRejectedWorks

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:

  1. It only holds if the API is unreachable except through the proxy. The control assumes the api Service 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.
  2. 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:

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.