> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a realm

> Create a new realm with the specified configuration.



## OpenAPI

````yaml /api-reference/5.9/fusion-api-api-docs.json post /realm-configs
openapi: 3.0.1
info:
  title: Fusion Proxy API
  description: Manage Fusion users, roles, realms, access tokens, and API keys.
  contact:
    name: Lucidworks
    url: www.lucidworks.com
    email: support@lucidworks.com
  license:
    name: License of API
    url: https://lucidworks.com/legal/developer-license-agreement/
  version: '5.9'
servers:
  - url: https://{FUSION HOST}/api
    description: Fusion
    variables:
      FUSION HOST:
        default: FUSION_HOST
        description: Your environment host.
security: []
tags:
  - name: Realm management
    description: >-
      Endpoints for creating, configuring, and managing authentication realms
      such as LDAP, SAML, OIDC, and others.
  - name: User management
    description: >-
      Endpoints for creating, updating, deleting, and retrieving Fusion users
      and their associated metadata.
  - name: Suggestions
    description: >-
      Endpoints that provide query suggestions or autocomplete results to
      improve search experiences.
  - name: API key management
    description: >-
      Endpoints for managing API keys used to authenticate Fusion services and
      integrations.
  - name: OAuth 2.0
    description: >-
      Endpoints that support OAuth 2.0 authentication, including token issuance
      and validation.
  - name: Role management
    description: >-
      Endpoints for creating and managing user roles and their associated
      permissions within Fusion.
  - name: System status
    description: >-
      Endpoints for retrieving basic system health, configuration, and
      authentication status.
externalDocs:
  description: Lucidworks Documentation
  url: https://doc.lucidworks.com/
paths:
  /realm-configs:
    post:
      tags:
        - Realm management
      summary: Create a realm
      description: Create a new realm with the specified configuration.
      operationId: createRealm
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/Realm'
                - $ref: '#/components/schemas/ApiKeyRealm'
                - $ref: '#/components/schemas/JWTRealm'
                - $ref: '#/components/schemas/KerberosRealm'
                - $ref: '#/components/schemas/LDAPRealm'
                - $ref: '#/components/schemas/OidcRealm'
                - $ref: '#/components/schemas/SAMLRealm'
                - $ref: '#/components/schemas/TrustedHTTPRealm'
            example:
              realmType: ldap
              name: dev-ldap3
              enabled: true
              roleNames:
                - developer
                - admin
              config:
                autoCreateUsers: true
                host: my.fusionhost.com
                ssl: true
                port: 10636
                ephemeralUsers: false
                login:
                  bindDnTemplate: uid={},ou=users,dc=security,dc=example,dc=com
        required: true
      responses:
        '201':
          description: Created
          content:
            '*/*':
              schema:
                anyOf:
                  - $ref: '#/components/schemas/Realm'
                  - $ref: '#/components/schemas/ApiKeyRealm'
                  - $ref: '#/components/schemas/JWTRealm'
                  - $ref: '#/components/schemas/KerberosRealm'
                  - $ref: '#/components/schemas/LDAPRealm'
                  - $ref: '#/components/schemas/OidcRealm'
                  - $ref: '#/components/schemas/SAMLRealm'
                  - $ref: '#/components/schemas/TrustedHTTPRealm'
              example:
                realmType: ldap
                id: ef32cba0-5340-4d73-b869-9f4faca45e10
                name: dev-ldap3
                enabled: true
                createdAt: '2025-10-31T17:06:33Z'
                config:
                  autoCreateUsers: true
                  host: my.fusionhost.com
                  ssl: true
                  port: 10636
                  ephemeralUsers: false
                  login:
                    bindDnTemplate: uid={},ou=users,dc=security,dc=example,dc=com
                roleNames:
                  - developer
                  - admin
        '409':
          description: Realm with name or ID already exists
          content:
            '*/*':
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Realm'
                  - $ref: '#/components/schemas/ApiKeyRealm'
                  - $ref: '#/components/schemas/JWTRealm'
                  - $ref: '#/components/schemas/KerberosRealm'
                  - $ref: '#/components/schemas/LDAPRealm'
                  - $ref: '#/components/schemas/OidcRealm'
                  - $ref: '#/components/schemas/SAMLRealm'
                  - $ref: '#/components/schemas/TrustedHTTPRealm'
components:
  schemas:
    Realm:
      title: Native realm
      required:
        - name
        - realmType
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: >-
            The name of the realm. This name will appear on the login screen of
            the UI, and will appear in user records to identify the realm they
            belong to.
        enabled:
          type: boolean
          description: >-
            If **true**, the realm is available for users to use with system
            authentication.
        createdAt:
          type: string
          format: date-time
          example: '2025-09-23T17:48:07Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-10-31T12:28:04Z'
        realmType:
          type: string
          description: >-
            Use the `/realm-configs` endpoint to get the list of valid realm
            types.
          example: native
      discriminator:
        propertyName: realmType
    ApiKeyRealm:
      title: API key realm
      required:
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
    JWTRealm:
      title: JWT realm
      required:
        - config
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
            config:
              $ref: '#/components/schemas/JwtRealmConfig'
    KerberosRealm:
      title: Kerberos realm
      required:
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
            config:
              $ref: '#/components/schemas/KerberosConfig'
    LDAPRealm:
      title: LDAP realm
      required:
        - config
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            config:
              $ref: '#/components/schemas/LdapRealmConfig'
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
    OidcRealm:
      title: OIDC realm
      required:
        - config
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            config:
              $ref: '#/components/schemas/OidcRealmConfig'
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
    SAMLRealm:
      title: SAML realm
      required:
        - config
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
            config:
              $ref: '#/components/schemas/SamlConfig'
    TrustedHTTPRealm:
      title: Trusted HTTP realm
      required:
        - name
      type: object
      allOf:
        - $ref: '#/components/schemas/Realm'
        - type: object
          properties:
            roleNames:
              type: array
              items:
                type: string
              description: >-
                Indicates which roles are dynamically applied to users in the
                realm.
            config:
              $ref: '#/components/schemas/TrustedConfig'
    JwtRealmConfig:
      required:
        - jwtIssuer
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        jwtIssuer:
          type: string
        signingKey:
          type: string
        jwkSetUri:
          type: string
          description: The URL of the authorization server’s JSON Web Key Set (JWKS).
        groups:
          $ref: '#/components/schemas/JwtGroups'
        userIdAttribute:
          type: string
        ephemeralUsers:
          type: boolean
          description: >-
            Prevents ephemeral users from being created in ZooKeeper during
            login. Enabling this property negates `config.autoCreateUsers`.
    KerberosConfig:
      required:
        - keytab
        - principal
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        principal:
          type: string
        keytab:
          type: string
        nameRules:
          type: string
    LdapRealmConfig:
      required:
        - host
        - login
        - port
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        host:
          type: string
        ssl:
          type: boolean
        port:
          type: integer
          format: int32
        ephemeralUsers:
          type: boolean
          description: >-
            Prevents ephemeral users from being created in ZooKeeper during
            login. Enabling this property negates `config.autoCreateUsers`.
        login:
          $ref: '#/components/schemas/LdapLogin'
        groups:
          $ref: '#/components/schemas/LdapGroups'
        bind:
          $ref: '#/components/schemas/Bind'
    OidcRealmConfig:
      required:
        - clientId
        - code
        - jwkSetUri
        - scope
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        groups:
          $ref: '#/components/schemas/Groups'
        code:
          $ref: '#/components/schemas/Code'
        clientId:
          type: string
        jwkSetUri:
          type: string
          description: The URL of the authorization server’s JSON Web Key Set (JWKS).
        userIdAttribute:
          type: string
        rolesAttribute:
          type: string
        scope:
          type: array
          items:
            type: string
        ephemeralUsers:
          type: boolean
          description: >-
            Prevents ephemeral users from being created in ZooKeeper during
            login. Enabling this property negates `config.autoCreateUsers`.
        logoutUrl:
          type: string
        proxy:
          $ref: '#/components/schemas/Proxy'
    SamlConfig:
      required:
        - certificateFingerprint
        - idpUrl
        - issuer
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        idpUrl:
          type: string
        issuer:
          type: string
        appIssuer:
          type: string
        certificateFingerprint:
          type: string
        userIdAttribute:
          type: string
        redirectUrl:
          type: string
        groups:
          $ref: '#/components/schemas/SamlGroups'
        ephemeralUsers:
          type: boolean
          description: >-
            Prevents ephemeral users from being created in ZooKeeper during
            login. Enabling this property negates `config.autoCreateUsers`.
        logoutUrl:
          type: string
    TrustedConfig:
      required:
        - identityKey
      type: object
      properties:
        autoCreateUsers:
          type: boolean
          description: >-
            Enables/disables the auto-creation of Fusion user accounts after
            users successfully authenticate for the first time.
        identityKey:
          type: string
        allowedIps:
          type: array
          items:
            type: string
        trustedProxyHeaders:
          type: array
          items:
            type: string
        groups:
          $ref: '#/components/schemas/TrustedGroups'
        ephemeralUsers:
          type: boolean
          description: >-
            Prevents ephemeral users from being created in ZooKeeper during
            login. Enabling this property negates `config.autoCreateUsers`.
    JwtGroups:
      type: object
      properties:
        groupKey:
          type: string
        roleMapping:
          type: array
          items:
            type: array
            items:
              type: string
    LdapLogin:
      type: object
      properties:
        bindDnTemplate:
          type: string
        kerberos:
          $ref: '#/components/schemas/KerberosConfig'
        searchBind:
          $ref: '#/components/schemas/SearchBind'
    LdapGroups:
      required:
        - search
      type: object
      properties:
        search:
          $ref: '#/components/schemas/Search'
        roleMapping:
          type: array
          items:
            type: array
            items:
              type: string
    Bind:
      required:
        - dn
        - password
      type: object
      properties:
        dn:
          type: string
        password:
          type: string
    Groups:
      type: object
      properties:
        roleMapping:
          type: array
          items:
            type: array
            items:
              type: string
    Code:
      required:
        - authorizationUri
        - redirectUri
        - tokenUri
      type: object
      properties:
        clientSecret:
          type: string
          description: >-
            A secret value shared between the application and the authentication
            server.
        redirectUri:
          type: string
          description: The URI to which the user will be redirected to after logging in.
        authorizationUri:
          type: string
          description: The authorization server URI.
        tokenUri:
          type: string
          description: The URI to get access token from.
    Proxy:
      type: object
      properties:
        host:
          type: string
        port:
          type: integer
          format: int32
        user:
          type: string
        password:
          type: string
    SamlGroups:
      type: object
      properties:
        groupNameAttribute:
          type: string
        roleMapping:
          type: array
          items:
            type: array
            items:
              type: string
    TrustedGroups:
      required:
        - key
      type: object
      properties:
        key:
          type: string
        roleMapping:
          type: array
          items:
            type: array
            items:
              type: string
        delimiter:
          type: string
    SearchBind:
      required:
        - baseDn
        - filterTemplate
      type: object
      properties:
        baseDn:
          type: string
        filterTemplate:
          type: string
    Search:
      required:
        - baseDn
        - filterTemplate
        - groupNameAttribute
      type: object
      properties:
        baseDn:
          type: string
        groupNameAttribute:
          type: string
        filterTemplate:
          type: string
        subtree:
          type: boolean

````