Extensions

Upload a custom extension

Uploads a new custom extension JAR to the workspace. The JAR is asynchronously scanned for malware; poll the returned extension's scan_status until it reaches ready before installing on a cluster.

Maximum body size is 150 MB.

Required scope: extensions:write

post/extensions

Request

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

Headers

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

Response

The request has succeeded and a new resource has been created as a result.

idstring uuid required
namestring required
display_namestring nullable

Friendly name shown in place of name when set. name never changes once an extension is catalogued; display_name lets the shown label change independently. Absent or null when the extension has none, in which case clients should fall back to name.

descriptionstring nullable required
source'platform' | 'custom' required
visibility'public' | 'private'
versionstring required

Active version of the extension.

keycloak_versionsstring[] required

Supported Keycloak major versions (e.g. ["25", "26"]).

parameter_type'env' | 'cli' | 'realm_attributes' required
repository_urlstring uri nullable required
icon_urlstring uri nullable required
documentation_urlstring uri nullable required
quick_start_stepsstring nullable required
usage_notesstring nullable required
scan_status'scanning' | 'ready' | 'rejected' | 'failed' required
scan_messagestring nullable required

Human-readable scan result. Present when scan_status is rejected (names the detected signature) or failed (says the scan could not complete).

original_jar_namestring nullable required

Original JAR filename provided at upload time. Only set for custom extensions.

file_size_bytesinteger nullable required

JAR file size in bytes. Only set for custom extensions.

uploaded_atstring date-time nullable required

When the extension was first uploaded. Only set for custom extensions.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Social Login Bundle",
  "description": "Adds social login providers for Google, GitHub, and Microsoft.",
  "source": "platform",
  "version": "3.1.0",
  "previous_versions": [],
  "keycloak_versions": [
    "25",
    "26"
  ],
  "parameter_type": "env",
  "parameters": [],
  "repository_url": null,
  "icon_url": null,
  "documentation_url": null,
  "quick_start_steps": null,
  "usage_notes": null,
  "scan_status": null,
  "scan_message": null,
  "original_jar_name": null,
  "file_size_bytes": null,
  "uploaded_at": "2025-01-15T10:00:00Z",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-03-20T14:30:00Z"
}

Changes

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