Service Accounts
Give an automation its own identity in KubeSense — a non-human account with its own role and API tokens, independent of any person.
A service account is a non-human identity for machine-to-machine access: a CI pipeline, an infrastructure-as-code job, a reporting script, or any automation that calls the KubeSense API. It has its own assigned role and its own API tokens, and it is independent of the person who created it — it keeps working after they change roles or leave the organisation.
This is the difference from a personal API key (see Developer API): a personal key acts as the human who made it and carries that person's live permissions. A service account acts as itself.
Manage service accounts from Settings → Service Accounts.
Administrator only: Only administrators can create or manage service accounts. Holding the Service Accounts permission is not enough on its own — management is restricted to the built-in Admin role.
When to use one
| Use case | Example |
|---|---|
| Configuration as code | A pipeline that creates or updates alerts, dashboards and SLOs |
| Scheduled analysis | A reporting job that reads metrics or logs on a cron |
| External integrations | An exporter that pulls permitted telemetry into another system |
| Autonomous automation | An agent acting within a fixed permission boundary |
Prefer a service account over a personal API key whenever the automation should outlive any individual and be governed and audited as its own actor.
Creating a service account
In Settings → Service Accounts, click Add, then set:
- Name — e.g.
production-alert-sync. Identifies the account everywhere. - Description — optional; what the automation is for. 3. Role — the account's permissions come entirely from this role. Pick one that grants only what the automation needs (see Role Access). The role also decides which clusters and namespaces the account sees (its data scope). To give an account its own permissions or cluster scope, create a dedicated role and assign it here.
The person who creates the account is recorded for accountability, but that record never affects authentication — the account is not disabled or deleted if they leave.
Issuing a token
Open a service account and choose Manage keys → Create key:
- Key label — a name for this token, e.g.
ci-primary. - Scopes — switch on the modules this token may use and choose Viewer (read) or Editor (write) for each. Scopes may only narrow the account's role: you can pick from what the role grants, never beyond it, and never Editor where the role is Viewer-only. At least one scope is required.
Click Generate key.
The secret is shown once: The token secret is displayed only once, immediately after you generate it. Copy it into your secret store now — KubeSense stores only a hash and can never show it again. If you lose it, revoke the token and issue a new one.
An account can hold several tokens at once, each with its own scopes — useful for giving different consumers different access, and for rotation (below).
Using a token
Authenticate API requests with the token in the X-API-Key header — the same header a personal API key uses:
curl -H "X-API-Key: <token>" \
"https://<your-kubesense-host>/api/logs/..."The token's effective access is the intersection of two things:
assigned role ∩ token scopesSo a token can never do more than its role allows — including the role's cluster and namespace data scope — and never more than its own scopes.
What a service account can and can't do
A service account reaches the product areas its role and token scopes allow — for example querying logs, traces and metrics (within the clusters and namespaces its role permits), discovering infrastructure, and reading or writing SLOs, alerts and dashboards.
Some areas are always off-limits to service accounts, regardless of role, because they are inherently tied to a human:
| Blocked for service accounts | Why |
|---|---|
| Managing users, roles and service accounts | Identity management is administrator-only, human-only |
| Creating or using personal API keys | Personal keys belong to a person, not an automation |
| Query Jobs (search jobs) | These are owned per-user and not yet service-account-aware |
| Profile, password and session actions | No human account behind the token |
Dashboard sharing: A service account can create and manage its own dashboards, and it sees public dashboards plus the ones it owns. It will not see a dashboard shared only with specific people — and a dashboard cannot be shared to a service account: the sharing picker lists users, not service accounts.
Managing the lifecycle
From the ⋮ menu on a service account, or inside Manage keys:
- Rotate a token — issue a new token, update the consumer to use it, then revoke the old one. Running both briefly during the switchover avoids downtime.
- Revoke a token — stops that token immediately; other tokens on the account keep working.
- Disable the account — suspends it: every token on it stops authenticating at once. Re-enable to resume.
- Delete the account — removes it and all its tokens.
A disabled or deleted account, and a revoked token, fail authentication straight away.
Security practices
- Least privilege. Assign the narrowest role, and scope each token to only the modules it needs, at Viewer unless it must write.
- Scope by role — assign a role whose data scope covers only the clusters and namespaces the automation needs.
- Store the secret in a secrets manager, never in source control.
- Rotate tokens periodically, and revoke any that are no longer used.
- One account per automation, so access and audit stay attributable to a single actor.