Install an extension on a cluster
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/extensions';
const options = {
method: 'POST',
headers: {
'API-Version': '2026-06-01.beta',
'API-Key': '<API-Key>',
'Content-Type': 'application/json'
},
body: '{"extension_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","parameters":{"THEME_COLOR":"#3b82f6"}}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}curl --request POST \
--url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/extensions \
--header 'API-Key: <API-Key>' \
--header 'API-Version: 2026-06-01.beta' \
--header 'Content-Type: application/json' \
--data '{ "extension_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "parameters": { "THEME_COLOR": "#3b82f6" } }'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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Parameter values keyed by the parameter key. Required parameters must be provided.
object
Example
{
"extension_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"parameters": {
"THEME_COLOR": "#3b82f6"
}
}Responses
Section titled “Responses”Returned for async operations. Poll the Location URL to track completion.
object
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.
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.
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.
Current parameter values. Values for sensitive parameters are omitted (null).
object
When the installation status last changed.
Example
{
"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"
}Headers
Section titled “Headers”URL of the resource being created or modified. Poll this endpoint to track completion.
The server could not understand the request due to invalid syntax.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Access is unauthorized.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
Returned when a workspace plan quota would be exceeded. required_plan indicates the minimum plan needed to complete the request.
object
Machine-readable identifier of the quota that was hit, so a client can tell
quotas apart without parsing detail. Known values include cluster_limit
(the workspace’s total cluster allowance), cluster_size_quota (the
allowance for the requested cluster size) and cluster_size (the requested
size is not offered on the plan at all). New values may be added.
How many of the resource the workspace currently has.
Maximum allowed by the current plan. 0 means the plan does not include the resource at all.
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"current_plan": "example",
"required_plan": "example",
"code": "example",
"current_usage": 1,
"current_limit": 1
}Access is forbidden.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The server cannot find the requested resource.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The request conflicts with the current state of the server.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
object
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com",
"errors": [
{
"field": "example",
"detail": "example",
"code": "example",
"value": "example"
}
]
}Client error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Headers
Section titled “Headers”Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}