scim-openapi.yaml

openapi: 3.0.3
info:
  title: SCIM 2.0 API
  version: 1.0.0
  description: >
    SCIM 2.0-compliant user provisioning API for Keycloak. All endpoints require OAuth2
    client credentials authentication (Bearer token). The client must be authenticated and
    the service account must have the realm role `scim-access`.

servers:
  - url: https://example.com/scim/v2

paths:
  /Users:
    get:
      summary: List users
      operationId: listUsers
      tags: [Users]
      description: >
        Returns a list of users in the current realm.

        Requires:
        - OAuth2 access token (Bearer token)
        - The client must be authenticated via client credentials
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          description: SCIM filter expression (e.g. `userName eq "alice@example.com"`)
          required: false
          schema:
            type: string
        - name: startIndex
          in: query
          schema:
            type: integer
        - name: count
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of users
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UsersList'

    post:
      summary: Create user
      operationId: createUser
      tags: [Users]
      description: >
        Creates a new user in the realm.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: User created
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'

  /Users/{id}:
    get:
      summary: Get user by ID
      operationId: findUser
      tags: [ Users ]
      description: >
        Retrieves a user by SCIM ID.
        
        Requires:
        - OAuth2 access token (Bearer token)
        - The client must be authenticated via client credentials
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          required: true
          description: SCIM user ID
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    put:
      summary: Update user
      operationId: updateUser
      tags: [ Users ]
      description: >
        Updates a user's full SCIM representation with the provided one.
        
        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User replaced
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request (e.g., invalid schema)
        '404':
          description: User not found
        '409':
          description: Conflict (e.g., username already exists)
    delete:
      summary: Delete user
      operationId: deleteUser
      tags: [Users]
      description: >
        Deletes a user by ID.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User deleted

    patch:
      summary: Update user
      operationId: patchUser
      tags: [Users]
      description: >
        Updates a user using SCIM PATCH semantics.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
      responses:
        '200':
          description: User updated
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'

  /Groups:
    get:
      summary: List groups
      operationId: listGroups
      tags: [Groups]
      description: >
        Returns a list of groups in the current realm.

        Requires:
        - OAuth2 access token (Bearer token)
        - The client must be authenticated via client credentials
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          description: SCIM filter expression (e.g. `displayName eq "Engineering"`)
          required: false
          schema:
            type: string
        - name: startIndex
          in: query
          schema:
            type: integer
        - name: count
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of groups
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/GroupsList'

    post:
      summary: Create group
      operationId: createGroup
      tags: [Groups]
      description: >
        Creates a new group in the realm.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '201':
          description: Group created
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/Group'

  /Groups/{id}:
    get:
      summary: Get group
      operationId: getGroup
      tags: [Groups]
      description: >
        Retrieves a group by ID.

        Requires:
        - OAuth2 access token (Bearer token)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Group found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/Group'
        '404':
          description: Group not found

    put:
      summary: Update group
      operationId: updateGroup
      tags: [ Groups ]
      security:
        - bearerAuth: [ ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '200':
          description: Group updated
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/Group'

    delete:
      summary: Delete group
      operationId: deleteGroup
      tags: [Groups]
      description: >
        Deletes a group by ID.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Group deleted

    patch:
      summary: Update group
      operationId: patchGroup
      tags: [Groups]
      description: >
        Updates a group using SCIM PATCH semantics.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
      responses:
        '200':
          description: Group updated
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/Group'

  /ResourceTypes:
    get:
      summary: List SCIM resource types
      operationId: listResourceTypes
      tags: [ Metadata ]
      description: >
        Returns the SCIM resource types supported by the server (e.g., User, Group).
        
        Required for SCIM discovery.
        
        Requires:
        - OAuth2 access token (Bearer token)
        - The client must be authenticated via client credentials
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: List of SCIM resource types
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ResourceTypeListResponse'

  /ResourceTypes/{id}:
    get:
      summary: Get resource type
      operationId: getResourceType
      tags: [ Metadata ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Resource type
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ResourceType'

  /Schemas:
    get:
      summary: List SCIM schemas
      operationId: listSchemas
      tags: [ Metadata ]
      description: >
        Returns the supported SCIM schemas used by Resources like Users and Groups.
        
        Required for SCIM discovery.
        
        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: List of SCIM schema definitions
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/SchemaListResponse'

  /Schemas/{id}:
    get:
      summary: Get SCIM schema
      operationId: getSchema
      tags: [ Metadata ]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SCIM schema definition
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/SchemaListItem'

  /ServiceProviderConfig:
    get:
      summary: Get SCIM service provider configuration
      operationId: getServiceProviderConfig
      tags: [Metadata]
      description: >
        Returns the service provider configuration, which describes SCIM capabilities such as
        patch support, filtering, bulk operations, sorting, authentication schemes, etc.

        Required for SCIM discovery.

        Requires:
        - OAuth2 access token (Bearer token)
        - The service account must have the realm role `scim-access`
      security:
        - bearerAuth: []
      responses:
        '200':
          description: SCIM service provider configuration
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ServiceProviderConfig'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

  schemas:
    UsersList:
      type: object
      properties:
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/User'

    User:
      type: object
      required:
        - userName
        - schemas
      properties:
        id:
          type: string
        userName:
          type: string
        name:
          type: object
          properties:
            givenName:
              type: string
            familyName:
              type: string
        emails:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
              primary:
                type: boolean
        active:
          type: boolean
        schemas:
          type: array
          items:
            type: string
        meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: true

    Group:
      type: object
      required:
        - schemas
        - displayName
      properties:
        id:
          type: string
        displayName:
          type: string
        members:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              display:
                type: string
        schemas:
          type: array
          items:
            type: string
        meta:
          $ref: '#/components/schemas/Meta'

    GroupsList:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          default:
            - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/Group'

    PatchRequest:
      type: object
      required:
        - schemas
        - Operations
      properties:
        schemas:
          type: array
          items:
            type: string
          example: [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ]
        Operations:
          type: array
          items:
            type: object
            required:
              - op
            properties:
              op:
                type: string
              path:
                type: string
                description: Attribute path to target
              value:
                description: >
                  Value to be applied. Can be a string, boolean, number, object, or array depending on the patch.
                type: object

    ResourceTypeListResponse:
      type: object
      required:
        - schemas
        - totalResults
        - startIndex
        - itemsPerPage
        - Resources
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
            - "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        totalResults:
          type: integer
          example: 2
        startIndex:
          type: integer
          example: 1
        itemsPerPage:
          type: integer
          example: 2
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ResourceType'

    ResourceType:
      type: object
      required:
        - schemas
        - id
        - name
        - endpoint
        - schema
        - meta
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
            - "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
        id:
          type: string
          example: "User"
        name:
          type: string
          example: "User"
        endpoint:
          type: string
          example: "/Users"
        description:
          type: string
          example: "User Account"
        schema:
          type: string
          example: "urn:ietf:params:scim:schemas:core:2.0:User"
        schemaExtensions:
          type: array
          items:
            type: object
            required:
              - schema
              - required
            properties:
              schema:
                type: string
              required:
                type: boolean
        meta:
          $ref: '#/components/schemas/Meta'

    SchemaListResponse:
      type: object
      required:
        - schemas
        - totalResults
        - startIndex
        - itemsPerPage
        - Resources
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
            - "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        totalResults:
          type: integer
          example: 1
        startIndex:
          type: integer
          example: 1
        itemsPerPage:
          type: integer
          example: 10
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/SchemaListItem'

    SchemaListItem:
      type: object
      required:
        - id
        - name
        - description
        - attributes
        - meta
      properties:
        id:
          type: string
          example: "urn:ietf:params:scim:schemas:core:2.0:User"
        name:
          type: string
          example: "User"
        description:
          type: string
          example: "SCIM core resource for representing users"
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/SchemaAttribute'
        schemas:
            type: array
            items:
                type: string
            example:
                - "urn:ietf:params:scim:schemas:core:2.0:Schema"
        meta:
          $ref: '#/components/schemas/Meta'

    SchemaAttribute:
      type: object
      required:
        - name
        - description
        - type
        - multiValued
        - required
        - caseExact
        - mutability
        - returned
        - uniqueness
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum: [string, boolean, decimal, integer, dateTime, reference, complex]
        multiValued:
          type: boolean
        required:
          type: boolean
        caseExact:
          type: boolean
        mutability:
          type: string
          enum: [readOnly, readWrite, immutable, writeOnly]
        returned:
          type: string
          enum: [always, never, default, request]
        uniqueness:
          type: string
          enum: [none, server, global]
        subAttributes:
          type: array
          items:
            $ref: '#/components/schemas/SchemaAttribute'
        referenceTypes:
          type: array
          items:
            type: string
              
    ServiceProviderConfig:
      type: object
      required:
        - schemas
        - patch
        - bulk
        - filter
        - changePassword
        - sort
        - etag
        - authenticationSchemes
        - meta
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
            - "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
        documentationUri:
          type: string
          format: uri
          example: "http://example.com/help/scim.html"
        patch:
          $ref: '#/components/schemas/ServiceFeatureSupport'
        bulk:
          type: object
          required:
            - supported
            - maxOperations
            - maxPayloadSize
          properties:
            supported:
              type: boolean
              example: true
            maxOperations:
              type: integer
              example: 1000
            maxPayloadSize:
              type: integer
              example: 1048576
        filter:
          type: object
          required:
            - supported
            - maxResults
          properties:
            supported:
              type: boolean
              example: true
            maxResults:
              type: integer
              example: 200
        changePassword:
          $ref: '#/components/schemas/ServiceFeatureSupport'
        sort:
          $ref: '#/components/schemas/ServiceFeatureSupport'
        etag:
          $ref: '#/components/schemas/ServiceFeatureSupport'
        authenticationSchemes:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticationScheme'
        meta:
          $ref: '#/components/schemas/Meta'

    ServiceFeatureSupport:
      type: object
      required:
        - supported
      properties:
        supported:
          type: boolean
          example: true

    AuthenticationScheme:
      type: object
      required:
        - name
        - description
        - type
        - primary
      properties:
        name:
          type: string
          example: "OAuth Bearer Token"
        description:
          type: string
          example: "Authentication scheme using the OAuth Bearer Token Standard"
        specUri:
          type: string
          format: uri
          example: "http://www.rfc-editor.org/info/rfc6750"
        documentationUri:
          type: string
          format: uri
          example: "http://example.com/help/oauth.html"
        type:
          type: string
          example: "oauthbearertoken"
        primary:
          type: boolean
          example: true

    Meta:
      type: object
      required:
        - location
        - resourceType
      properties:
        location:
          type: string
          format: uri
          example: "https://example.com/v2/ServiceProviderConfig"
        resourceType:
          type: string
          example: "ServiceProviderConfig"
        created:
          type: string
          format: date-time
          example: "2010-01-23T04:56:22Z"
        lastModified:
          type: string
          format: date-time
          example: "2011-05-13T04:42:34Z"