API Key Scopes

API keys authenticate programmatic access to the SkaleData API. Each key has a scopes list that controls which endpoints it can access.

Available scopes

Scope	Grants access to
`full`	All endpoints (default for new keys)
`clusters:read`	List and get clusters, clouds, node pools, pod list/logs
`clusters:write`	Create, update, upgrade, destroy clusters. Manage clouds, node pools, GitHub integration, cancel jobs
`apps:read`	List and get applications, health checks
`apps:deploy`	Deploy images, upload DAGs, get deploy scripts, registry tokens, dev credentials
`apps:manage`	Create, update, delete, restart applications
`jobs:read`	List and get jobs
`terminal:exec`	Terminal pod setup

How scopes work

A key with the full scope bypasses all scope checks — it can call any endpoint that accepts API key auth.
Non-full keys must have the specific scope required by each endpoint. If the scope is missing, the API returns 403 Forbidden with the message API key missing required scope: <scope>.
Some endpoints are user-only and reject API key auth entirely (billing management, API key management, data plane tokens).

Creating scoped keys

When creating an API key via POST /api-keys, pass a scopes array:


curl -X POST https://api.skaledata.com/api-keys \
  -H "Authorization: Bearer <clerk-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-deploy",
    "scopes": ["apps:deploy", "clusters:read"]
  }'

The returned key can deploy images and read cluster info, but cannot create or destroy clusters.

Scope combinations

Common patterns for CI/CD and automation:

Use case	Scopes
Full access (default)	`["full"]`
CI/CD deploy pipeline	`["apps:deploy", "clusters:read"]`
Monitoring / dashboards	`["clusters:read", "apps:read", "jobs:read"]`
Cluster management automation	`["clusters:read", "clusters:write"]`
DAG sync bot	`["apps:deploy"]`

Endpoints that reject API keys

These endpoints require a user session (Clerk JWT) and will return 403 if called with an API key:

POST/DELETE /api-keys/* — API key management
POST /billing/* — billing management
POST /clusters/{id}/data-plane-token — data plane handoff (needs user email)