Cluster Extensions

Install an extension on a cluster

Installs an extension on the cluster. The installation is processed asynchronously; poll GET /clusters/{cluster_id}/extensions/{extension_id} until status reaches active or failed.

The extension's scan_status must be ready before installation.

Required scope: clusters:extensions:write

post/clusters/{cluster_id}/extensions

Request

  • Base URL: http://localhost:8000
  • URL: http://localhost:8000/clusters/{cluster_id}/extensions
  • Auth: API key in header API-Key

Path parameters

cluster_idstring uuid required

Headers

API-Version'2026-06-01.beta' required

Request body

extension_idstring uuid required
parametersobject

Parameter values keyed by the parameter key. Required parameters must be provided.

Example request

{
  "extension_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parameters": {
    "THEME_COLOR": "#3b82f6"
  }
}

Response

Returned for async operations. Poll the Location URL to track completion.

extension_idstring uuid required
extension_namestring required
extension_source'platform' | 'custom' required
status'installing' | 'active' | 'failed' | 'removing' required
installed_versionstring required

Version currently running on the cluster. For platform extensions this is the upstream release string of the installed build (not necessarily semver, for example 1.4.1-SNAPSHOT), or unknown when it cannot be determined. For custom extensions it is the uploader-supplied version.

available_versionstring nullable required

Version the cluster would get by upgrading now. For platform extensions it is the build published for the cluster's Keycloak version (unknown when that build states no version), and null when no build supports the cluster's Keycloak version. For custom extensions it is the latest uploaded version.

upgrade_availableboolean required

Whether upgrading would install a different build. For platform extensions it compares the installed build with the one published for the cluster's Keycloak version, so republishing an unchanged catalog never sets it. For custom extensions it is set when a version was published after the install. Always false when the install is not active or is pinned by Skycloak support.

parametersobject required

Current parameter values. Values for sensitive parameters are omitted (null).

installed_atstring date-time required
last_status_change_atstring date-time nullable required

When the installation status last changed.

Example response

{
  "extension_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "extension_name": "Social Login Bundle",
  "extension_source": "platform",
  "status": "active",
  "installed_version": "3.0.0",
  "available_version": "3.1.0",
  "upgrade_available": true,
  "parameters": {},
  "installed_at": "2025-02-01T09:00:00Z",
  "last_status_change_at": "2025-02-01T09:05:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.