API
Authentication & Scopes

Authentication & Scopes

The Skycloak API uses API keys for authentication. Each key is scoped to a workspace and granted a set of scopes that control which operations it can perform.

API Keys

Creating an API Key

  1. Log in to your Skycloak dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give it a name and select the required scopes
  5. Copy the key immediately. It won’t be shown again

Using an API Key

Pass your API key in the API-Key request header on every request:

curl https://api.skycloak.io/clusters \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"
⚠️
Treat API keys like passwords. Never commit them to version control or expose them in client-side code. Use environment variables or a secrets manager.

Key Lifecycle

API keys can have the following statuses:

Status Description
active Key is valid and can be used
revoked Key has been manually revoked
expired Key has passed its expiry date

Keys can be revoked or rotated at any time from the dashboard or via the API.

Rotating an API Key

Rotating a key generates a new secret and immediately invalidates the old one — there is no grace period.

⚠️
No grace period. The previous key stops working immediately upon rotation. Plan accordingly for zero-downtime deployments.

Security Best Practices

  • Principle of least privilege — grant only the scopes your integration actually needs
  • Rotate regularly — rotate keys on a schedule or whenever team members with access leave
  • Use expiry dates — set expires_at on short-lived integrations so keys expire automatically
  • Never share keys — each integration or CI/CD pipeline should use its own dedicated key
  • Revoke immediately — if a key is compromised, revoke it right away

OAuth 2.0 Client Credentials

ℹ️

The Skycloak Public API itself authenticates with API keys (the API-Key header described above). Use API keys for all Skycloak API integrations.

OAuth 2.0 client credentials come into play one level down, for automating the contents of your own Keycloak. Each cluster has a per-cluster automation client that your tooling (Terraform, CI/CD, scripts, MCP servers, AI agents) uses with the client credentials grant to manage realms, clients, users, and roles inside your Keycloak. That is a separate credential from your Public API key. See Automating your Keycloak.

Scopes

Scopes control which operations an API key can perform. Follow the principle of least privilege — only grant the scopes your integration actually needs.

Write scopes imply their read counterpart. For example, clusters:write automatically grants clusters:read.

Available Scopes

See the Settings > API Keys for the full list of available scopes and their descriptions.

Insufficient Scope Errors

If a request is made with a key that lacks the required scope, the API returns 403 Forbidden:

{
  "type": "https://skycloak.io/docs/api/errors#forbidden",
  "title": "Forbidden",
  "detail": "API key does not have the required scope: clusters:write",
  "status": 403
}

See Error Handling for more detail on error responses.

Last updated on
Getting Started with the APIError Handling