Imports

Start a realm import

Imports a realm (configuration, users, and credentials) into the cluster via the Keycloak Admin API. Preflight validates the target Keycloak version, refuses a name collision, and blocks on missing password-hash providers. Poll GET /realm-imports/{import_id} until status is completed or failed.

Required scope: clusters:imports:write

post/clusters/{cluster_id}/realms/import

Request

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

Path parameters

cluster_idstring uuid required

Headers

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

Request body

source_kind'upload' | 'stored'
upload_s3_keystring

Object key of a previously-uploaded artifact (from the upload-url endpoint). Required when source_kind is upload.

source_export_idstring

A stored realm export id. Required when source_kind is stored.

passwordstring

Password to decrypt an encrypted artifact. Omit for a bare foreign JSON.

Example request

{
  "source_kind": "upload",
  "upload_s3_key": "realm-imports/uploads/ws/abc.zip.enc",
  "password": "a-strong-passphrase"
}

Response

Returned when a realm import has been accepted for processing. Poll the resource until status is completed or failed.

idstring uuid required
cluster_idstring uuid required
realmstring required

The imported realm's name, derived from the artifact.

source_kind'upload' | 'stored' required
status'pending' | 'processing' | 'completed' | 'failed' required
progressinteger required

Percent complete, 0-100.

source_versionstring nullable

Keycloak version that produced the artifact.

target_versionstring nullable

Target cluster's Keycloak version at import time.

error_messagestring nullable

Failure description. Only set when status is failed.

created_atstring date-time required
completed_atstring date-time nullable

Example response

{
  "id": "7b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "cluster_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "realm": "cust-brasilia",
  "source_kind": "upload",
  "status": "completed",
  "progress": 100,
  "source_version": "26.6.1",
  "target_version": "26.6.2",
  "error_message": null,
  "created_at": "2026-07-19T15:00:00Z",
  "completed_at": "2026-07-19T15:03:00Z"
}

Changes

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