Cloud-IAM | DOCS

Appearance

🛠️ Ready to Build?

Apply what you’ve learned and deploy Keycloak on Cloud-IAM.

Try Cloud-IAM

How to manage Marketplace extensions through the Cloud-IAM API ​

You can manage your releases programmatically using the Cloud-IAM REST API, which is useful for automation, CI/CD pipelines, or building custom integrations.

Before making API calls, obtain a Bearer token using a Service Account. See How to authenticate with the Cloud-IAM API for details.

List extensions for your organization ​

shell
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/organizations/{organizationId}/marketplace/extensions"

Example response:

json
[
  {
    "extensionId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Extension",
    "availability": "GA",
    "documentation": "# Documentation\nMarkdown content...",
    "summary": "Short description of the extension",
    "isMandatory": false,
    "isPublished": true,
    "howToInstall": "Installation instructions...",
    "logo": "https://storage.example.com/logo.png",
    "categories": [
      {
        "categoryId": "cat-001",
        "name": "Authentication"
      }
    ],
    "screenshots": [
      {
        "extensionId": "550e8400-e29b-41d4-a716-446655440000",
        "rank": 1,
        "filepath": "https://storage.example.com/screenshot-1.png",
        "extension": "png"
      }
    ],
    "latestRelease": {
      "releaseId": "rel-001",
      "version": "1.2.0",
      "status": "VALIDATED"
    },
    "organizationId": "org-001",
    "organizationName": "My Organization",
    "visibility": "PUBLIC"
  }
]

Key response fields:

  • extensionId — unique identifier of the extension
  • name — display name
  • availability — GA (generally available)
  • isPublished — whether the extension is visible in the marketplace
  • visibility — PRIVATE. In the initial phase, all extensions are set to PRIVATE and this value cannot be changed
  • categories — list of associated categories
  • latestRelease — the most recent release (or null if none)
  • organizationId / organizationName — owning organization

TIP

The endpoint always returns 200 OK, even when the list is empty.

List releases for an extension ​

Returns a paginated list of releases for a given extension:

shell
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/marketplace/extensions/{extensionId}/releases?page=0&size=20"

Query parameters:

  • page — page number, 0-indexed (default: 0)
  • size — items per page (default: 20)
  • sort — sort field and direction (default: updated_at,DESC)

Example response:

json
{
  "content": [
    {
      "extensionId": "ext-001",
      "releaseId": "rel-001",
      "version": "1.2.0",
      "availability": "GA",
      "status": "VALIDATED",
      "jars": [
        {
          "jarId": "jar-001",
          "releaseId": "rel-001",
          "jar": "s3://bucket/path/to/extension.jar",
          "filename": "my-extension-1.2.0.jar"
        }
      ],
      "compatibility": ["25.0.0", "24.0.6"],
      "spis": ["org.keycloak.authentication.AuthenticatorFactory"],
      "releaseNote": "Bug fixes and performance improvements.",
      "updatedAt": "2026-03-20T14:30:00Z"
    }
  ],
  "page": {
    "size": 20,
    "totalElements": 5,
    "totalPages": 1,
    "number": 0
  }
}

Key response fields:

  • releaseId — unique identifier of the release
  • version — version number
  • status — current validation status (see Release validation process)
  • jars — list of JAR files associated with the release
  • compatibility — list of compatible Keycloak versions
  • spis — list of Keycloak SPIs implemented by the extension
  • releaseNote — release notes
  • updatedAt — last modification timestamp
  • page.totalElements / page.totalPages — pagination info

Add a release to an extension ​

Adding a release involves uploading JAR files and specifying compatible Keycloak versions. This triggers an automated compatibility validation pipeline.

Step 1 — Upload the release ​

shell
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F 'releaseData={"version":"1.3.0","availability":"GA","keycloakVersions":["kc-25.0.0","kc-24.0.6"],"keycloakSpi":["org.keycloak.authentication.AuthenticatorFactory"],"releaseNote":"Added multi-realm support."};type=application/json' \
  -F "jars=@my-extension-1.3.0.jar" \
  "https://api.cloud-iam.com/marketplace/extensions/{extensionId}/releases"

releaseData fields:

  • version (required) — release version number
  • availability — GA
  • keycloakVersions (required) — list of compatible Keycloak version IDs
  • keycloakSpi — list of Keycloak SPIs implemented by the extension
  • releaseNote — release notes

Returns 204 No Content on success.

Step 2 — Automatic validation ​

Once the release is created, the system automatically triggers a compatibility check pipeline for each declared Keycloak version. The pipeline verifies that the extension JAR is compatible with the target Keycloak image.

You can monitor the release status by polling:

shell
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/marketplace/extensions/{extensionId}/releases/{releaseId}"

Step 3 — Force validation (optional) ​

If automatic validation fails or is not applicable, you can manually force-validate the release:

shell
curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/marketplace/extensions/{extensionId}/releases/{releaseId}/force-validation"

Returns 204 No Content on success. This sets the release and all its associated Keycloak version statuses to VALIDATED.

How the compatibility pipeline works ​

When a release is created, the system triggers a GitLab CI pipeline for each declared Keycloak version. The pipeline:

  1. Downloads the extension JAR files
  2. Loads them against the target Keycloak image
  3. Verifies keycloak starts successfully with the extension
  4. Reports the result back

Auto-compatibility check on new Keycloak version ​

If your extension has autoCompatibilityCheck enabled, it will be automatically tested against new major Keycloak versions when they are released. If your extension is already compatible with the current latest Keycloak version, the compatibility pipeline will run against the new major version and — if successful — the extension will be declared compatible automatically.

Install extensions on a deployment ​

shell
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "extensionIds": ["ext-001", "ext-002"],
    "applyNow": true
  }' \
  "https://api.cloud-iam.com/deployments/{deploymentId}/marketplace/extensions"

Request body fields:

  • extensionIds (required) — list of extension IDs to install
  • applyNow (required) — set to true to trigger a redeployment immediately, or false to install without applying

Returns 204 No Content on success.

WARNING

The deployment must be in a RUNNING state. The request will fail if the deployment is not running.

List installed extensions on a deployment ​

shell
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/deployments/{deploymentId}/marketplace/extensions"

Returns a paginated list of extensions installed on the deployment, including whether an update is available for each one.

Upgrade an extension ​

When a newer compatible release is available (updateAvailable: true), you can upgrade the extension:

shell
curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/deployments/{deploymentId}/marketplace/extensions/{extensionId}?apply=true"

Query parameters:

  • apply — set to true to trigger a redeployment immediately (default: true)

Returns 204 No Content on success

Remove an extension from a deployment ​

shell
curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.cloud-iam.com/deployments/{deploymentId}/marketplace/extensions/{extensionId}?apply=true"

Query parameters:

  • apply — set to true to trigger a redeployment immediately (default: true)

Returns 204 No Content on success.

WARNING

Mandatory extensions cannot be removed from a deployment.

Release validation process ​

How the compatibility pipeline works ​

When a release is created, the system triggers a GitLab CI pipeline for each declared Keycloak version. The pipeline:

  1. Downloads the extension JAR files
  2. Loads them against the target Keycloak image
  3. Verifies keycloak starts successfully with the extension
  4. Reports the result back

Auto-compatibility check on new Keycloak version ​

If your extension has autoCompatibilityCheck enabled, it will be automatically tested against new major Keycloak versions when they are released. If your extension is already compatible with the current latest Keycloak version, the compatibility pipeline will run against the new major version and — if successful — the extension will be declared compatible automatically.

The freedom of open source, the power of Cloud-IAM

Deploy your dedicated Keycloak instantly on Cloud-IAM with enterprise-grade infrastructure.

Launch Now