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:

bash

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.