Authentication

Tenant-scoped API routes require bearer authentication. The public plan endpoints, GET /plans and GET /plans/{name}, do not.

API keys

API keys are the standard way to authenticate to tenant-scoped API routes.

Generate them in the console under API Keys as a tenant admin. Each key is tenant-scoped, role-scoped, and returned once at creation time, so store the raw value immediately before using it in the standard Authorization: Bearer header.

Roles

Role	Access
admin	Read and write access, including cluster changes, member management, and API key management
readonly	Read-only access to tenant resources and cluster connection details

Use an API key

export KUPE_API_KEY="kupe_..."
export KUPE_TENANT="<tenant>"

curl \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/clusters"

Key handling guidance

• store keys in your CI secret store, not in source control
• use readonly unless the workflow needs to make changes
• set expiresAt for temporary access when possible
• revoke keys as soon as they are no longer needed

Only admins can create, list, and revoke API keys.

Headers

Tenant-scoped requests use the standard bearer header:

Authorization: Bearer <api-key>

Rate limiting

The API applies per-IP rate limiting and returns 429 Too Many Requests with a Retry-After header when you need to back off.

Repeated authentication failures also trigger exponential backoff, so fix bad credentials before retrying in a loop.

For error handling and retry guidance, see Errors, Retries, and Rate Limits.