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": "[email protected]", "password": "your-password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "orgId": "org_xyz789",
  "role": "admin",
  "plan": "pro",
  "mustChangePassword": false
}

The same call also sets the token as an HttpOnly auth_token cookie, so a browser session doesn't need to handle the token itself; it's returned in the response body for header-based clients (agents, scripts, API consumers). Tokens expire after 24 hours (there's no expiresAt field in the response to check this against). 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 right away, since it's 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 still using the revoked key will get 401 unauthorized on its next request.

Authentication errors

Every authentication failure on a tenant-scoped request comes back the same way: 401 with {"error":"unauthorized"}. The response doesn't distinguish the underlying cause, so if you get this, check for any of the following:

Possible cause	Fix
Missing `Authorization` header, cookie, or `X-API-Key`	Add one of the three
JWT signature invalid or tampered	Re-authenticate
JWT has passed its 24-hour expiry	Call `/auth/login` for a new token
JWT was issued without an `org_id` claim	Re-authenticate, or contact support if it persists
API key revoked	Generate a new key in Settings → API Keys

A suspended organization is a separate case: requests authenticate fine but get 402 with {"error":"org_suspended"} instead of 401.

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