openapi: 3.0.1
info:
  title: SCIM 2.0 Users API
  description: >
    This document specifies **SCIM 2.0 User Management RESTful API** for **WSO2
    Identity Server**.
  version: 1.0.0
servers:
  - url: https://{serverUrl}/t/{tenantDomain}/scim2
    variables:
      serverUrl:
        default: localhost:9443
      tenantDomain:
        default: carbon.super
security:
  - OAuth2: []
  - BasicAuth: []
paths:
  /Users:
    get:
      tags:
        - Users Endpoint
      summary: Filter users
      description: >
        This API returns users according to the filter, sort and pagination
        parameters. Pagination is not supported across user stores and LDAP
        multi-attribute group filtering. However, filtering is supported across
        multiple user stores.

        By default, duplicate user entries in the SCIM2 users response are
        persisted. To remove the duplicate user entries, add the following
        configuration to the deployment.toml file. </br> </br>


        ** Note

        According to the SCIM specification, the `totalResutls` attribute should
        return total number of results returned by the list or query operation. 
        But due to the limitation of the LDAP user store, when we use the
        pagination paramters, we cannot get total number of users in the
        database. So, we are returning the total number of users per page as the
        `totalResults`. This is only applicable for the LDAP user store. The
        JDBC user store is working according to the specification.


        [scim2]

        remove_duplicate_users_in_users_response = true


        <b>Scope(Permission) required:</b>`internal_user_mgt_list`
            
      operationId: getUser
      parameters:
        - name: attributes
          in: query
          description: SCIM defined attributes parameter.
          schema:
            type: string
        - name: excludedAttributes
          in: query
          description: SCIM defined excludedAttribute parameter.
          schema:
            type: string
        - name: filter
          in: query
          description: >
            Filter expression for filtering. Supported filters are ‘Ew’, ‘Eq’,
            ‘Co’, ‘Sw’, ‘and’.
          schema:
            type: string
        - name: startIndex
          in: query
          description: The 1-based index of the first query result
          schema:
            type: integer
            format: int32
        - name: count
          in: query
          description: Specifies the desired maximum number of query results per page.
          schema:
            type: integer
            format: int32
        - name: domain
          in: query
          description: The name of the user store where filtering needs to be applied.
          schema:
            type: string
      responses:
        '200':
          description: Valid users are found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserObjectListResponseObject'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/scim2/Users' \
            -H 'accept: application/scim+json'
    post:
      tags:
        - Users Endpoint
      summary: Create user
      description: >
        This API creates a user and returns the user details along with the
        user's unique ID.

         
        <b>Scope(Permission) required:</b>`internal_user_mgt_create`
            
      operationId: createUser
      parameters:
        - name: attributes
          in: query
          description: SCIM defined attributes parameter.
          schema:
            type: string
        - name: excludedAttributes
          in: query
          description: SCIM defined excludedAttribute parameter.
          schema:
            type: string
      requestBody:
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/UserObject'
        required: false
      responses:
        '201':
          description: User is created.
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserResponseObject'
        '400':
          description: Invalid Input
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorInvalidInput'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
        '500':
          description: Internal Server Error
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServerError'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'POST' \
            'https://localhost:9443/scim2/Users' \
            -H 'accept: application/scim+json' \
            -H 'Content-Type: application/scim+json' \
            -d '{
            "schemas": [],
            "name": {
              "givenName": "Kim",
              "familyName": "Berry"
            },
            "userName": "kim",
            "password": "abc123",
            "emails": [
              {
                "type": "home",
                "value": "kim@gmail.com",
                "primary": true
              },
              {
                "type": "work",
                "value": "kim@wso2.com"
              }
            ],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "1234A",
              "manager": {
                "value": "Taylor"
              }
            }
            }'
      x-codegen-request-body-name: body
  /Users/.search:
    post:
      tags:
        - Users Endpoint
      summary: Search users
      description: >
        This API returns users according to the filter, sort and pagination
        parameters.

         <b>Scope(Permission) required:</b>`internal_user_mgt_list`
            
      operationId: getUsersByPost
      requestBody:
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/UserSearchRequestObject'
        required: false
      responses:
        '200':
          description: Valid users are found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserObjectListResponseObject'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'POST' \
            'https://localhost:9443/scim2/Users/.search' \
            -H 'accept: application/scim+json' \
            -H 'Content-Type: application/scim+json' \
            -d '{
            "schemas": [
              "urn:ietf:params:scim:api:messages:2.0:SearchRequest"
            ],
            "attributes": [
              "name.familyName",
              "userName"
            ],
            "filter": "userName sw ki and name.familyName co err",
            "domain": "PRIMARY",
            "startIndex": 1,
            "count": 10
            }'
      x-codegen-request-body-name: body
  /Users/{id}:
    get:
      tags:
        - Users Endpoint
      summary: Get user by ID
      description: |
        Return user details if a user found.

         <b>Scope(Permission) required:</b>`internal_user_mgt_view`
            
      operationId: getUser by id
      parameters:
        - name: id
          in: path
          description: Unique ID of the resource type.
          required: true
          schema:
            type: string
        - name: attributes
          in: query
          description: SCIM defined attributes parameter.
          schema:
            type: string
        - name: excludedAttributes
          in: query
          description: SCIM defined excludedAttribute parameter.
          schema:
            type: string
      responses:
        '200':
          description: Valid user is found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserResponseObject'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/scim2/Users/{user-id}' \
            -H 'accept: application/scim+json'
    put:
      tags:
        - Users Endpoint
      summary: Update user - PUT
      description: >
        This API updates user details and returns the updated user details using
        a PUT operation.

         <b>Scope(Permission) required:</b>`internal_user_mgt_update`
            
      operationId: updateUser
      parameters:
        - name: id
          in: path
          description: Unique ID of the resource type.
          required: true
          schema:
            type: string
        - name: attributes
          in: query
          description: SCIM defined attributes parameter.
          schema:
            type: string
        - name: excludedAttributes
          in: query
          description: SCIM defined excludedAttribute parameter.
          schema:
            type: string
      requestBody:
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/UserUpdateObject'
        required: false
      responses:
        '200':
          description: Valid user is found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserResponseObject'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'PUT' \
            'https://localhost:9443/scim2/Users/{user-id}' \
            -H 'accept: application/scim+json' \
            -H 'Content-Type: application/scim+json' \
            -d '{
            "schemas": [],
            "name": {
              "givenName": "Kim",
              "familyName": "Berry"
            },
            "userName": "kim",
            "emails": [
              {
                "type": "home",
                "value": "kim@gmail.com",
                "primary": true
              },
              {
                "type": "work",
                "value": "kim@wso2.com"
              }
            ],
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "1234A",
              "manager": {
                "value": "Taylor"
              }
            }
            }'
      x-codegen-request-body-name: body
    delete:
      tags:
        - Users Endpoint
      summary: Delete user by ID
      description: |
        This API deletes a user using the user's unique ID.

          <b>Scope(Permission) required:</b>`internal_user_mgt_delete`
      operationId: deleteUser
      parameters:
        - name: id
          in: path
          description: Unique ID of the resource type.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User is deleted
          content: {}
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'DELETE' \
            'https://localhost:9443/scim2/Users/{user-id}' \
            -H 'accept: */*'
    patch:
      tags:
        - Users Endpoint
      summary: Update user - PATCH
      description: >
        This API updates user details and returns the updated user details using
        a PATCH operation.

          
         <b>Scope(Permission) required:</b>`internal_user_mgt_update`

        <b>Supported Operations:</b>    `add`, `replace`, `remove`
            
      operationId: patchUser
      parameters:
        - name: id
          in: path
          description: Unique id of the resource type.
          required: true
          schema:
            type: string
        - name: attributes
          in: query
          description: SCIM defined attributes parameter.
          schema:
            type: string
        - name: excludedAttributes
          in: query
          description: SCIM defined excludedAttribute parameter.
          schema:
            type: string
      requestBody:
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/PatchOpperationInput'
        required: false
      responses:
        '200':
          description: Valid user is found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/UserResponseObject'
        '401':
          description: Unauthorized
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'PATCH' \
            'https://localhost:9443/scim2/Users/user-id' \
            -H 'accept: application/scim+json' \
            -H 'Content-Type: application/scim+json' \
            -d '{
            "schemas": [
              "urn:ietf:params:scim:api:messages:2.0:PatchOp"
            ],
            "Operations": [
              {
                "op": "add",
                "value": {
                  "nickName": "shaggy"
                }
              }
            ]
            }'
      x-codegen-request-body-name: body
components:
  schemas:
    UserObject:
      required:
        - password
      type: object
      properties:
        schemas:
          type: object
          properties: {}
          example: []
        name:
          type: object
          properties:
            givenName:
              type: string
              example: Kim
            familyName:
              type: string
              example: Berry
        userName:
          type: string
          example: kim
        password:
          type: string
          example: abc123
        emails:
          type: array
          example:
            - type: home
              value: kim@gmail.com
              primary: true
            - type: work
              value: kim@wso2.com
          items:
            type: object
            properties: {}
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          type: object
          properties:
            employeeNumber:
              type: string
              example: 1234A
            manager:
              type: object
              properties:
                value:
                  type: string
                  example: Taylor
    UserResponseObject:
      required:
        - meta
      type: object
      properties:
        meta:
          type: object
          properties:
            created:
              type: string
              example: '2018-08-17T10:34:29Z'
            location:
              type: string
              example: >-
                https://localhost:9443/scim2/Users/008bba85-451d-414b-87de-c03b5a1f4217
            lastModified:
              type: string
              example: '2018-08-17T10:34:29Z'
            resourceType:
              type: string
              example: User
        schemas:
          type: object
          properties: {}
          example:
            - urn:ietf:params:scim:schemas:core:2.0:User
            - urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
        username:
          type: string
          example: PRIMARY/kim
        id:
          type: string
          example: 008bba85-451d-414b-87de-c03b5a1f4217
        name:
          type: object
          properties:
            givenName:
              type: string
              example: Kim
            familyName:
              type: string
              example: Berry
        emails:
          type: array
          example:
            - type: home
              value: kim@gmail.com
              primary: true
            - type: work
              value: kim@wso2.com
          items:
            type: object
            properties: {}
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          type: object
          properties:
            employeeNumber:
              type: string
              example: 1234A
            manager:
              type: object
              properties:
                value:
                  type: string
                  example: Taylor
        roles:
          type: object
          properties: {}
          example:
            - type: default
              value: Internal/everyone
    UserUpdateObject:
      type: object
      properties:
        schemas:
          type: object
          properties: {}
          example: []
        name:
          type: object
          properties:
            givenName:
              type: string
              example: Kim
            familyName:
              type: string
              example: Berry
        userName:
          type: string
          example: kim
        emails:
          type: array
          example:
            - type: home
              value: kim@gmail.com
              primary: true
            - type: work
              value: kim@wso2.com
          items:
            type: object
            properties: {}
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          type: object
          properties:
            employeeNumber:
              type: string
              example: 1234A
            manager:
              type: object
              properties:
                value:
                  type: string
                  example: Taylor
    PatchOpperationInput:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: object
            example: urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationMeItem'
    OperationMeItem:
      type: object
      properties:
        op:
          type: string
          enum:
            - add
            - remove
            - replace
        value:
          type: object
          properties:
            nickName:
              type: string
              example: shaggy
    UserObjectListResponseObject:
      type: object
      properties:
        totalResults:
          type: integer
          example: 1
        startIndex:
          type: integer
          example: 1
        itemsPerPage:
          type: integer
          example: 1
        schemas:
          type: object
          properties: {}
          example:
            - urn:ietf:params:scim:api:messages:2.0:ListResponse
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/UserResponseObject'
    UserSearchRequestObject:
      type: object
      example:
        schemas:
          - urn:ietf:params:scim:api:messages:2.0:SearchRequest
        attributes:
          - name.familyName
          - userName
        filter: userName sw ki and name.familyName co err
        domain: PRIMARY
        startIndex: 1
        count: 10
    ErrorInvalidInput:
      required:
        - detail
        - status
      type: object
      properties:
        status:
          type: string
          example: '400'
        schemas:
          type: string
          example: urn:ietf:params:scim:api:messages:2.0:Error
        scimType:
          type: string
          example: invalidSyntax
        detail:
          type: string
          example: Request is unparsable, syntactically incorrect, or violates schema.
    ErrorUnauthorized:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          example: '401'
        schemas:
          type: string
          example: urn:ietf:params:scim:api:messages:2.0:Error
        scimType:
          type: string
          example: Unauthorized
    ErrorForbidden:
      required:
        - status
      type: object
      properties:
        status:
          type: string
          example: '403'
        schemas:
          type: string
          example: urn:ietf:params:scim:api:messages:2.0:Error
        scimType:
          type: string
          example: Forbidden
    ErrorInternalServerError:
      required:
        - detail
        - status
      type: object
      properties:
        status:
          type: string
          example: '500'
        schemas:
          type: string
          example: urn:ietf:params:scim:api:messages:2.0:Error
        detail:
          type: string
          example: Internal Server Error.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth/authorize
          tokenUrl: https://localhost:9443/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants read and write access to administrative information
