Authentication

K8Cost supports two authentication methods: JWT tokens (for interactive use) and API keys (for programmatic access).

JWT Authentication

Obtain a token by posting credentials to the login endpoint:

curl -X POST https://app.k8cost.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-password"}'

Response:

{
  "token": "eyJhbGciOi...",
  "expires_at": "2026-04-02T14:00:00Z",
  "user": {
    "id": "uuid",
    "email": "you@company.com",
    "role": "admin"
  }
}

Use the token in subsequent requests:

curl https://app.k8cost.com/api/v1/clusters \
  -H "Authorization: Bearer eyJhbGciOi..."

Tokens expire after 24 hours. Use the refresh endpoint:

curl -X POST https://app.k8cost.com/auth/refresh \
  -H "Authorization: Bearer eyJhbGciOi..."

API Key Authentication

API keys are ideal for scripts, CI/CD pipelines, and the K8Cost CLI. Create one from Settings → API Tokens.

curl https://app.k8cost.com/api/v1/clusters \
  -H "X-API-Key: k8c_live_abc123..."

API keys don't expire unless revoked. Each key inherits the permissions of the user who created it.

Agent Authentication

The K8Cost agent uses a cluster-specific token generated during setup:

env:
  - name: K8COST_API_TOKEN
    valueFrom:
      secretKeyRef:
        name: k8cost-agent
        key: api-token

Agent tokens have limited scope — they can only submit metrics for their assigned cluster.

Rate Limits

Auth Method	Limit
JWT	100 requests/minute
API Key	200 requests/minute
Agent Token	20 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1711929600

RBAC Roles

Role	Permissions
admin	Full access to all resources, settings, and billing
editor	Read/write clusters, recommendations, alerts. No billing or user management
viewer	Read-only access to all dashboards and reports

Custom roles can be created with granular permissions like clusters:read, recommendations:write, budgets:read.