Getting Started with the API

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