Getting Started with the API

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

This guide walks you through making your first Skycloak API call.

Prerequisites

Before you begin, you’ll need:

A Skycloak account with an active workspace
curl or your preferred HTTP client

Step 1: Create an API Key

Log in to your Skycloak dashboard
Select API keys in the left sidebar (under Workspace)
Click Create API Key
Give it a name (e.g., “My First Key”)
Select the clusters:write scope
Copy the key immediately – it won’t be shown again

For a full explanation of authentication methods and available scopes, see Authentication & Scopes.

Step 2: Make Your First API Call

List your clusters to verify authentication is working:

curl https://api.skycloak.io/clusters \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"

You should receive a JSON response with your clusters:

[
  {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "production",
    "type": "keycloak",
    "status": "available",
    "size": "small",
    "version": "26.5.5",
    "location": "us",
    "management_mode": "full",
    "url": "https://production.example.skycloak.io",
    "sso_enabled": true,
    "http_relative_path": "",
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:32:00Z"
  }
]

Step 3: Create a Cluster

Create a new cluster by sending a POST request with the desired configuration:

curl -X POST https://api.skycloak.io/clusters \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-cluster",
    "size": "small",
    "location": "us",
    "version": "26.5.5"
  }'

The API responds with 201 Created – the cluster is being provisioned:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-first-cluster",
  "type": "keycloak",
  "status": "provisioning",
  "size": "small",
  "version": "26.5.5",
  "location": "us",
  "management_mode": "full",
  "url": "",
  "sso_enabled": true,
  "http_relative_path": "",
  "features": [],
  "features_disabled": [],
  "created_at": "2026-02-15T10:30:00Z",
  "updated_at": "2026-02-15T10:30:00Z"
}

Poll the cluster by ID (see Step 4) until its status changes from provisioning.

Step 4: Check Cluster Status

Clusters are created asynchronously. Poll until the status changes:

curl https://api.skycloak.io/clusters/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "API-Key: $SKYCLOAK_API_KEY" \
  -H "API-Version: 2026-06-01.beta"

Status transitions:

provisioning → available (success)
provisioning → failed (failure)

Next Steps

Authentication & Scopes – full list of scopes and auth options
Versioning – required API version header
API Reference – interactive endpoint documentation
Rate Limiting – understand request limits
Error Handling – error formats and retry strategies