Imports and exports

Start a bulk user import (asynchronous)

Creates a user.import job. The Idempotency-Key is also bound to the job.

Parameters

Request body

application/json · required

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "default": "proudauth.user-import.v1",
      "description": "The records format (MIG-002); an unsupported format is refused with 422. GET /user-import-formats lists the formats."
    },
    "source_system": {
      "type": "string",
      "minLength": 1
    },
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "minItems": 1,
      "maxItems": 1000,
      "description": "User records; see api/schemas/user-import.schema.json."
    },
    "dry_run": {
      "type": "boolean"
    },
    "trust_email_verification": {
      "type": "boolean"
    },
    "verification_reason": {
      "type": "string",
      "minLength": 10,
      "description": "Required with trust_email_verification, which also requires realm.users.verification.override (USR-005)."
    },
    "allow_owner_roles": {
      "type": "boolean"
    },
    "import_totp": {
      "type": "boolean",
      "description": "Authorizes importing totp_secret seeds (MIG-007). Requires realm.users.credentials.manage and an MFA session; without it, a record carrying totp_secret fails. Seeds are base32 (80 to 512 bits), re-encrypted under this deployment's keys and audited as mfa.totp.imported."
    }
  },
  "required": [
    "source_system",
    "users"
  ],
  "additionalProperties": false
}

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Idempotent-Replayed": {
    "$ref": "#/components/headers/Idempotent-Replayed"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "Retry-After": {
    "$ref": "#/components/headers/Retry-After"
  }
}

Operation importUsers · Schema definitions · OpenAPI contract

List supported user import formats

The import formats this release accepts (MIG-002), each with the source products it covers, its schema, what it carries over and what it cannot. POST /user-imports declares one in format; compatibility is never inferred from source_system.

Parameters

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation listUserImportFormats · Schema definitions · OpenAPI contract

Reconcile imported users with the source

Counts what the realm holds now for the users imported from one source_system (MIG-012): accounts by state, memberships, privileged assignments, sign-in methods and verified emails. Expected counts from the source export, given as expected_* parameters, are compared and every difference is listed in mismatches. Returns no credentials or contact data. 404 when nothing was imported from the source.

Parameters

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation reconcileUserImport · Schema definitions · OpenAPI contract

Export the realm data

Portable exit (OSS-008, MIG-014): a job (realm.export) writes the realm as NDJSON records {kind, data} with stable IDs - header (format proudauth.realm-export.v1 and the excluded list), configuration, user, organization, membership, group, role_assignment, authorization_policy, project, service_principal, identity_provider, webhook, hook. Credential secrets, keys, live tokens and audit evidence are excluded. Download through POST /jobs/{id}/downloads; the permission is re-checked when the job runs and at download.

Parameters

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation createRealmDataExport · Schema definitions · OpenAPI contract

List the first-party migration adapters

The source products this release converts (MIG-002, MIG-018): Keycloak, ZITADEL and SuperTokens, each with the source versions it accepts and was tested with, how to produce the export and what converts, converts with loss or is unsupported. An export of another version is refused; compatibility is never inferred from the product name.

Parameters

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation listMigrationAdapters · Schema definitions · OpenAPI contract

Convert a source export and report what would carry over (read-only)

Converts a Keycloak, ZITADEL or SuperTokens export in memory (MIG-018) and returns its capability report: per entity type the items converted, converted with loss (and what was lost), unsupported (credential algorithms or parameters outside the accepted bounds, passkeys, client secrets, flows and policies, roles without a reviewed translation) and ignored, plus the mapping review and a mapping template. target checks the conversion against the realm without writing (MIG-003): which target organizations exist (by the external ID an earlier run set, or by the slug the mapping names), conflict (an existing organization only sharing the proposed slug, MIG-004) or will be created; which mapped organization roles exist; which source IDs are already imported or were deleted (MIG-017); and which records meet an email or username of another account. The response names records by source ID only and never returns credentials, seeds or contact data; the exports are not stored. Nothing is imported: identity-cli migrate-from --apply submits the documents through POST /organizations and POST /user-imports. The request is bounded by limits.max_body_bytes (256 KiB by default): plan larger exports with identity-cli migrate-from --plan.

Parameters

Request body

application/json · required

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "keycloak",
        "zitadel",
        "supertokens"
      ]
    },
    "source_version": {
      "type": "string",
      "description": "The source product's version. Required when the export does not state it (ZITADEL; the SuperTokens core API list); when the export states one, this must be that version or a leading part of it such as its major version (26 for 26.8.0), otherwise 422. A version outside the adapter's supported range is refused with 422."
    },
    "source_system": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$",
      "description": "Name qualifying every source ID (import_mappings); default <source>-<realm or app>."
    },
    "exports": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "The export documents as produced by the source (a Keycloak directory export has a realm file and users files)."
    },
    "mapping": {
      "$ref": "#/components/schemas/MigrationMapping"
    },
    "keep_attributes": {
      "type": "boolean",
      "description": "Keep source attributes and metadata as administrator-only metadata."
    },
    "import_totp": {
      "type": "boolean",
      "description": "Carry compatible TOTP seeds over (the import itself needs import_totp and its authority)."
    }
  },
  "required": [
    "source",
    "exports"
  ],
  "additionalProperties": false
}

Responses

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  },
  "WWW-Authenticate": {
    "$ref": "#/components/headers/WWW-Authenticate"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

{
  "X-Request-Id": {
    "$ref": "#/components/headers/X-Request-Id"
  }
}

Operation planMigration · Schema definitions · OpenAPI contract