How-to Guides
Mint an API key
Create a Kubeadapt API key from the dashboard with the right scopes for one integration.
Every integration that calls the Kubeadapt REST API needs its own key. This guide walks the dashboard flow, the scope decision, and the one-time-secret handling rules.
1. Open the API Keys page
Go to app.kubeadapt.io → Settings → API Keys → + Create Key.
The dialog has two inputs: a Name and a Scopes picker. Every key issued today covers every cluster in your tenant — there is no per-cluster allow-list in the UI yet.
2. Name the key
Use the integration name, not a person's name: grafana-export, finance-chargeback, ci-cost-check. Descriptive names make later audits and revocations far easier.
The field accepts up to 255 characters and is required.
3. Pick the minimum scopes
The dashboard lists every *:read scope as a toggleable pill, grouped by category. Tick only what the integration actually calls — at least one scope is required to enable Create Key. Read-only access is enforced server-side.
Available scopes:
| Category | Scope | Unlocks |
|---|---|---|
| Organization | organization:read | Tenant metadata |
| Clusters | clusters:read | Cluster inventory |
| Workloads | namespaces:read | Namespace listing |
| Workloads | workloads:read | Deployments, StatefulSets, DaemonSets, Jobs |
| Infrastructure | nodes:read | Node inventory and capacity |
| Recommendations | recommendations:read | Right-sizing and savings suggestions |
| Attribution | teams:read | Team allocations |
| Attribution | departments:read | Department allocations |
| Attribution | cost_explorer:read | Cost Explorer queries |
Common minimum sets:
| Integration | Scopes |
|---|---|
| Read-only Grafana / BI exporter | organization:read, clusters:read, namespaces:read, workloads:read, nodes:read |
| Finance chargeback pipeline | teams:read, departments:read, organization:read |
| SRE savings dashboard | recommendations:read, clusters:read, nodes:read |
| Cost Explorer query proxy | cost_explorer:read |
Adding scopes later means minting a second key — the dashboard does not edit existing keys.
See Permission Scopes for the full endpoint-to-scope mapping.
4. Cluster visibility
Every key issued from the dashboard sees every cluster in the tenant, including clusters added after the key was minted. A per-cluster allow-list picker is on the roadmap.
If you need to gate an integration to a subset of clusters today, filter by cluster_id in your downstream code, or contact support to scope a key manually.
5. Copy the key immediately
The full key is shown once. Copy it into a password manager or your secrets store before navigating away.
6. Verify the key
Run a 200 OK smoke test before deploying the key to production:
curl -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
"https://public-api.kubeadapt.io/v1/organization"A 401 UNAUTHORIZED means the header is wrong or the key was not accepted. A 403 FORBIDDEN means the key works but is missing the organization:read scope — mint a new key with the right scopes (existing keys cannot be edited).
See Authentication for the full 401 vs 403 contract.
See also
- Rotate an API key — zero-downtime cutover from old to new.
- Authentication — the wire-level contract.
- Permission Scopes — the full scope catalog.