Keycloak Identity Providers API

openapi: 3.2.0
info:
  title: Keycloak Identity Providers API
  version: '1.0'
  description: 'Operations tagged Identity Providers across 2 of this provider''s published API definitions: keycloak-admin-rest-api-openapi.yml, keycloak-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{host}/admin/realms
  description: Keycloak Admin REST API
  variables:
    host:
      default: localhost:8080
      description: Keycloak server host and port
tags:
- name: Identity Providers
  description: Manage identity providers for federated authentication
paths:
  /{realm}/identity-provider/instances:
    parameters:
    - $ref: '#/components/parameters/realm'
    get:
      operationId: getIdentityProviders
      summary: Keycloak List identity providers
      description: Returns a list of identity providers configured in the realm.
      tags:
      - Identity Providers
      responses:
        '200':
          description: A list of identity provider representations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProviderRepresentation'
      security:
      - bearerAuth: []
    post:
      operationId: createIdentityProvider
      summary: Keycloak Create an identity provider
      tags:
      - Identity Providers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderRepresentation'
      responses:
        '201':
          description: Identity provider created successfully
      security:
      - bearerAuth: []
    servers:
    - url: https://{host}/admin/realms
      description: Keycloak Admin REST API
      variables:
        host:
          default: localhost:8080
          description: Keycloak server host and port
  /{realm}/identity-provider/instances/{alias}:
    parameters:
    - $ref: '#/components/parameters/realm'
    - name: alias
      in: path
      required: true
      description: The alias of the identity provider
      schema:
        type: string
    get:
      operationId: getIdentityProvider
      summary: Keycloak Get an identity provider
      tags:
      - Identity Providers
      responses:
        '200':
          description: An identity provider representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProviderRepresentation'
        '404':
          description: Identity provider not found
      security:
      - bearerAuth: []
    put:
      operationId: updateIdentityProvider
      summary: Keycloak Update an identity provider
      tags:
      - Identity Providers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderRepresentation'
      responses:
        '204':
          description: Identity provider updated
      security:
      - bearerAuth: []
    delete:
      operationId: deleteIdentityProvider
      summary: Keycloak Delete an identity provider
      tags:
      - Identity Providers
      responses:
        '204':
          description: Identity provider deleted
      security:
      - bearerAuth: []
    servers:
    - url: https://{host}/admin/realms
      description: Keycloak Admin REST API
      variables:
        host:
          default: localhost:8080
          description: Keycloak server host and port
  /admin/realms/{realm}/identity-provider/import-config:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    post:
      tags:
      - Identity Providers
      summary: Import identity provider from JSON body
      description: Import identity provider from uploaded JSON file
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
      operationId: postAdminRealmsByRealmIdentityProviderImportConfig
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: List identity providers
      parameters:
      - name: briefRepresentation
        in: query
        description: 'Boolean which defines whether brief representations are returned (default: false)'
        schema:
          type: boolean
      - name: capability
        in: query
        description: Filter by identity providers capability
        schema:
          type: string
      - name: first
        in: query
        description: Pagination offset
        schema:
          format: int32
          type: integer
      - name: max
        in: query
        description: Maximum results size (defaults to 100)
        schema:
          format: int32
          type: integer
      - name: realmOnly
        in: query
        description: 'Boolean which defines if only realm-level IDPs (not associated with orgs) should be returned (default: false)'
        schema:
          type: boolean
      - name: search
        in: query
        description: Filter specific providers by name. Search can be prefix (name*), contains (*name*) or exact ("name"). Default prefixed.
        schema:
          type: string
      - name: type
        in: query
        description: Filter by identity providers type
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProviderRepresentation_2'
      operationId: getAdminRealmsByRealmIdentityProviderInstances
      x-operation-id-source: derived
    post:
      tags:
      - Identity Providers
      summary: Create a new identity provider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderRepresentation_2'
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
        '409':
          description: Conflict
      operationId: postAdminRealmsByRealmIdentityProviderInstances
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Get the identity provider
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProviderRepresentation_2'
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAlias
      x-operation-id-source: derived
    put:
      tags:
      - Identity Providers
      summary: Update the identity provider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderRepresentation_2'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '409':
          description: Conflict
      operationId: putAdminRealmsByRealmIdentityProviderInstancesByAlias
      x-operation-id-source: derived
    delete:
      tags:
      - Identity Providers
      summary: Delete the identity provider
      responses:
        '200':
          description: OK
      operationId: deleteAdminRealmsByRealmIdentityProviderInstancesByAlias
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/export:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Export public broker configuration for identity provider
      parameters:
      - name: format
        in: query
        description: Format to use
        schema:
          type: string
      responses:
        '200':
          description: OK
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasExport
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/management/permissions:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Return object stating whether client Authorization permissions have been…
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementPermissionReference'
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasManagementPermissions
      x-operation-id-source: derived
    put:
      tags:
      - Identity Providers
      summary: Return object stating whether client Authorization permissions have been…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagementPermissionReference'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagementPermissionReference'
      operationId: putAdminRealmsByRealmIdentityProviderInstancesByAliasManagementPermissions
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/mapper-types:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Get mapper types for identity provider
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/IdentityProviderMapperTypeRepresentation'
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasMapperTypes
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/mappers:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Get mappers for identity provider
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/IdentityProviderMapperRepresentation'
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasMappers
      x-operation-id-source: derived
    post:
      tags:
      - Identity Providers
      summary: Add a mapper to identity provider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderMapperRepresentation'
      responses:
        '200':
          description: OK
      operationId: postAdminRealmsByRealmIdentityProviderInstancesByAliasMappers
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/mappers/{id}:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Get mapper by id for the identity provider
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityProviderMapperRepresentation'
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasMappersById
      x-operation-id-source: derived
    put:
      tags:
      - Identity Providers
      summary: Update a mapper for the identity provider
      parameters:
      - name: id
        in: path
        description: Mapper id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityProviderMapperRepresentation'
      responses:
        '204':
          description: No Content
      operationId: putAdminRealmsByRealmIdentityProviderInstancesByAliasMappersById
      x-operation-id-source: derived
    delete:
      tags:
      - Identity Providers
      summary: Delete a mapper for the identity provider
      parameters:
      - name: id
        in: path
        description: Mapper id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      operationId: deleteAdminRealmsByRealmIdentityProviderInstancesByAliasMappersById
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/instances/{alias}/reload-keys:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    - name: alias
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Reaload keys for the identity provider if the provider supports it, "true" is…
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: boolean
      operationId: getAdminRealmsByRealmIdentityProviderInstancesByAliasReloadKeys
      x-operation-id-source: derived
  /admin/realms/{realm}/identity-provider/providers/{provider_id}:
    parameters:
    - name: realm
      in: path
      description: realm name (not id!)
      required: true
      schema:
        type: string
    get:
      tags:
      - Identity Providers
      summary: Get the identity provider factory for that provider id
      parameters:
      - name: provider_id
        in: path
        description: The provider id to get the factory
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
      operationId: getAdminRealmsByRealmIdentityProviderProvidersByProviderId
      x-operation-id-source: derived
components:
  parameters:
    realm:
      name: realm
      in: path
      required: true
      description: The name of the realm
      schema:
        type: string
  schemas:
    IdentityProviderRepresentation:
      type: object
      description: Representation of a federated identity provider
      properties:
        alias:
          type: string
          description: Unique alias for the identity provider
        displayName:
          type: string
        internalId:
          type: string
          readOnly: true
        providerId:
          type: string
          description: The identity provider type (e.g., oidc, saml, google, github, facebook)
        enabled:
          type: boolean
        trustEmail:
          type: boolean
        storeToken:
          type: boolean
        addReadTokenRoleOnCreate:
          type: boolean
        authenticateByDefault:
          type: boolean
        linkOnly:
          type: boolean
        firstBrokerLoginFlowAlias:
          type: string
        postBrokerLoginFlowAlias:
          type: string
        config:
          type: object
          additionalProperties:
            type: string
          description: Provider-specific configuration (e.g., clientId, clientSecret, authorizationUrl, tokenUrl for OIDC providers)
    ManagementPermissionReference:
      type: object
      properties:
        enabled:
          type: boolean
        resource:
          type: string
        scopePermissions:
          type: object
          additionalProperties:
            type: string
    ConfigPropertyRepresentation:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        helpText:
          type: string
        type:
          type: string
        defaultValue: {}
        options:
          type: array
          items:
            type: string
        secret:
          type: boolean
        required:
          type: boolean
        readOnly:
          type: boolean
    IdentityProviderMapperTypeRepresentation:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        category:
          type: string
        helpText:
          type: string
        properties:
          type: array
          items:
            $ref: '#/components/schemas/ConfigPropertyRepresentation'
    OrganizationIdentityProviderLinkRepresentation:
      type: object
      properties:
        organizationId:
          type: string
        autoMembership:
          type: boolean
        membershipType:
          type: string
    IdentityProviderMapperRepresentation:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        identityProviderAlias:
          type: string
        identityProviderMapper:
          type: string
        config:
          type: object
          additionalProperties:
            type: string
    IdentityProviderRepresentation_2:
      type: object
      properties:
        alias:
          type: string
        displayName:
          type: string
        internalId:
          type: string
        providerId:
          type: string
        enabled:
          type: boolean
        updateProfileFirstLoginMode:
          type: string
          deprecated: true
        trustEmail:
          type: boolean
        storeToken:
          type: boolean
        addReadTokenRoleOnCreate:
          type: boolean
        authenticateByDefault:
          type: boolean
        linkOnly:
          type: boolean
        hideOnLogin:
          type: boolean
        firstBrokerLoginFlowAlias:
          type: string
        postBrokerLoginFlowAlias:
          type: string
        organizationLinks:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationIdentityProviderLinkRepresentation'
        config:
          type: object
          additionalProperties:
            type: string
        types:
          type: array
          items:
            type: string
        updateProfileFirstLogin:
          type: boolean
          deprecated: true
        organizationId:
          type: string
          writeOnly: true
          deprecated: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token obtained from the Keycloak token endpoint. Use the master realm admin credentials or a service account with appropriate realm-management roles.
x-refined-from:
- keycloak-admin-rest-api-openapi.yml
- keycloak-openapi.json