Authentication

Authenticate API requests using JWT bearer tokens or API keys.

The KubeWatch API supports two authentication methods: JWT bearer tokens for user-initiated requests (dashboard, direct API use) and API keys for agent and programmatic access.

JWT Bearer Token

Obtain a token

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-06-13T10:00:00Z",
  "user": {
    "id": "user_abc123",
    "email": "you@example.com",
    "orgId": "org_xyz789"
  }
}

Tokens expire after 24 hours. Request a new token by calling /auth/login again.

Use the token

Include the token in the Authorization header on every API request:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://YOUR_KUBEWATCH_URL/api/v1/agents

API Keys

API keys are long-lived credentials generated in the dashboard. They never expire until explicitly revoked.

Create an API key

Go to Settings → API Keys
Click Create Key
Enter a descriptive name (e.g., prod-agent, ci-monitor)
Copy the key, it is shown only once

API keys look like: kw_live_abc123xyz456...

Use the API key

Pass the key in the X-API-Key header:

curl -H "X-API-Key: kw_live_abc123xyz456..." \
  https://YOUR_KUBEWATCH_URL/api/v1/agents

API keys are scoped to the organization they were created in. They have the same permissions as an admin user for the purpose of reading metrics and managing agents.

Revoking an API key

Go to Settings → API Keys, find the key, and click Revoke. Revocation takes effect immediately, any agent using the revoked key will receive 401 unauthorized on its next request.

Authentication errors

Error	Cause	Fix
`401 unauthorized`	Missing, expired, or invalid token/key	Re-authenticate or check the key
`401 invalid token`	JWT signature invalid or tampered	Re-authenticate
`401 missing org_id claim`	JWT was issued without an org claim	Re-authenticate; contact support if persists
`401 token expired`	JWT has passed its `expiresAt` time	Call `/auth/login` for a new token

Security recommendations

Store API keys in environment variables or a secrets manager, never in code or version control
Use short-lived JWT tokens for interactive sessions and API keys for long-running agents
Rotate API keys periodically or immediately after a suspected exposure
Use separate API keys for each agent so you can revoke individual agents without affecting others