swagger: '2.0'
info:
  title: SCIM API v1.1 protected with OAuth2 scopes
  version: v1.1
  description: >-
    The SCIM Protocol is an application-level, REST protocol for provisioning
    and managing identity data on the web. The protocol supports creation,
    modification, retrieval, and discovery of core identity resources.

    This version of SCIM API is protected with OAuth2 scopes and for certain
    actions must be sent an access token containing the necessary scopes. For
    the GET, POST, PUT, and PATCH operations we are checking for the existence
    of scopes that allow you to perform operations on the user. To retrieve or
    change user attributes, you must have the OAuth2 scopes needed for that
    specific operation (SCIM:user:get, SCIM:user:query, SCIM:user:post,
    SCIM:user:put, SCIM:user:patch, SCIM:user:delete)

    For more comprehensive information and illustrative examples, we highly
    recommend visiting the following page:
    https://developer.onewelcome.com/documentation/scim-example-messages
  termsOfService: 'https://www.onewelcome.com'
  contact:
    name: scim@onewelcome.com
  license:
    name: OneWelcome License
    url: 'https://www.onewelcome.com'
host: www.onewelcome.com
basePath: /
paths:
  /secure/v1.1/Users:
    get:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: filter
          description: >
            Specifies the filter used to search users matching a specific
            criteria. There are multiple operators that can be used for
            filtering,

            such as binary operators, logical operators, grouping operators, and
            unary operators.

              **Binary operators:**
              <table>
              <thead>
              <tr>
              <th>Operator</th>
              <th>Description</th>
              <th>Behavior</th>
              </tr>
              </thead>
              <tbody>
              <tr>
              <td>eq</td>
              <td>equal</td>
              <td>The attribute and operator values must be identical for a match.</td>
              </tr>
              <tr>
              <td>co</td>
              <td>contains</td>
              <td>The entire operator value must be a substring of the attribute value for a match.</td>
              </tr>
              <tr>
              <td>sw</td>
              <td>starts with</td>
              <td>The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value.</td>
              </tr>
              <tr>
              <td>gt</td>
              <td>greater than (>)</td>
              <td>If the attribute value is greater than operator value, there is a match.</td>
              </tr>
              <tr>
              <td>ge</td>
              <td>greater than or equal (>=)</td>
              <td>If the attribute value is greater than or equal to the operator value, there is a match.</td>
              </tr>
              <tr>
              <td>lt</td>
              <td>less than (<)</td>
              <td>If the attribute value is less than operator value, there is a match.</td>
              </tr>
              <tr>
              <td>le</td>
              <td>less than or equal (<=)</td>
              <td>If the attribute value is less than or equal to the operator value, there is a match.</td>
              </tr>
              </tbody>
              </table>

              **Logical operators:**
              <table>
              <thead>
              <tr>
              <th>Operator</th>
              <th>Description</th>
              <th>Behavior</th>
              </tr>
              </thead>
              <tbody>
              <tr>
              <td>and</td>
              <td>Logical and</td>
              <td>The filter is only a match if both expressions evaluate to true.</td>
              </tr>
              <tr>
              <td>or</td>
              <td>Logical or</td>
              <td>The filter is a match if either expression evaluates to true.</td>
              </tr>
              </tbody>
              </table>

              **Unary operators:**
              <table>
              <thead>
              <tr>
              <th>Operator</th>
              <th>Description</th>
              <th>Behavior</th>
              </tr>
              </thead>
              <tbody>
              <tr>
              <td>pr</td>
              <td>present (has value)</td>
              <td>If the attribute has a non-empty value, or if it contains a non-empty node for complex attributes there is a match.</td>
              </tr>
              <tr>
              <td>npr</td>
              <td>not present</td>
              <td></td>
              </tr>
              </tbody>
              </table>

              **Grouping operators:**
              <table>
              <thead>
              <tr>
              <th>Operator</th>
              <th>Description</th>
              <th>Behavior</th>
              </tr>
              </thead>
              <tbody>
              <tr>
              <td>()</td>
              <td>Precedence grouping</td>
              <td>Boolean expressions may be grouped using parentheses to change the standard order of operations; i.e., evaluate OR logical operators before logical AND operators.</td>
              </tr>
              </tbody>
              </table>

            Multiple filter criteria can be used, an example of such a filter
            being:

            * filter=username co
            "username_value"&sortBy=username&sortOrder=ascending

            * filter=emails.value co "email" or username eq "username" and
            name.familyName eq "User_Family_Name" or name.middle eq
            "User_Middle_Name" and (age gt "16" and age lt "50")


            In case there are multiple attributes with the same name in
            different schemas (core and extension), and the attribute from the

            filter does not contain the schema in the name, then the filtering
            will be executed on the attribute from core schema, if any,

            otherwise an error will be thrown. Assuming the above, if it is
            required to filter the attribute from the extension schema the

            attribute name should contain the extension schema as well.

            Considering an example in which groups attribute is present in both
            core schema `urn:scim:schemas:core:1.0` and extension schema

            `urn:scim:schemas:extension:onewelcome:1.0`, the filtering would
            look as follows:
              * filter core schema attribute: `filter = groups EQ "group1"`
              * filter extension schema attribute: `filter =  urn:scim:schemas:extension:onewelcome:1.0:groups EQ "someOtherGroup"`
          in: query
          required: false
          type: string
        - name: startIndex
          description: Index of the first search result.
          in: query
          required: false
          type: integer
          format: int32
        - name: count
          description: Specifies the desired maximum number of search results per page.
          in: query
          required: false
          type: integer
          format: int32
        - name: sortBy
          description: >-
            The sortBy parameter specifies the attribute whose value shall be
            used to order the returned responses.
          in: query
          required: false
          type: string
        - name: sortOrder
          description: >-
            The order in which the sortBy parameter is applied. Allowed values
            are: asc, desc, ascending and descending.
          in: query
          required: false
          type: string
      responses:
        '200':
          description: Paginated user results.
          schema:
            $ref: '#/definitions/UsersDTO'
        '400':
          description: Bad query parameters.
          schema:
            $ref: '#/definitions/ScimErrorResource'
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ScimErrorResource'
      security:
        - OAuth2:
            - 'SCIM:user:query'
      operationId: getUsers
      summary: Retrieve users
      description: >-
        The endpoint is protected and allows user to get multiple users by
        filtering with optional paging and sorting. The provided access token
        must include 'SCIM:user:query' scope to be able to operate.
    post:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: user
          description: The user to be created
          schema:
            $ref: '#/definitions/MapOfStringsAndObjects'
          in: body
          required: false
        - name: typeOfCreation
          description: The type of user creation.
          in: query
          required: false
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/User'
        '201':
          description: User is created.
          schema:
            $ref: '#/definitions/User'
        '400':
          description: Bad user data
          schema:
            $ref: '#/definitions/ScimErrorResource'
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ScimErrorResource'
        '409':
          description: User already exists
          schema:
            $ref: '#/definitions/ScimErrorResource'
      security:
        - OAuth2:
            - 'SCIM:user:post'
      operationId: createUser
      summary: Create a new user
      description: >-
        The endpoint is used to create a new user. To be able to call this
        endpoint, an access token having the scope 'SCIM:user:post' is required.
  '/secure/v1.1/Users/{userId}':
    get:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: userId
          description: Unique identifier of the user
          in: path
          required: true
          type: string
      responses:
        '200':
          description: User found.
          schema:
            $ref: '#/definitions/User'
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
        '404':
          description: User not found
          schema:
            $ref: '#/definitions/ScimErrorResource'
      security:
        - OAuth2:
            - 'SCIM:user:get'
      operationId: getUser
      summary: Retrieve a specific user
      description: >-
        The endpoint is used to retrieve an user identified by the userId path
        parameter. In order to be able to call this endpoint, an access token
        having the scope 'SCIM:user:get' is required.
    put:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: userId
          description: Identifier of the user to update
          in: path
          required: true
          type: string
        - name: userMap
          description: Object with patch attribute names and values
          schema:
            $ref: '#/definitions/MapOfStringsAndObjects'
          in: body
          required: true
      responses:
        '200':
          description: User successfully updated.
          schema:
            $ref: '#/definitions/User'
        '204':
          description: No Content
        '400':
          description: Invalid parameters. Validation failed.
          schema:
            $ref: '#/definitions/ScimErrorResource'
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
      security:
        - OAuth2:
            - 'SCIM:user:put'
      operationId: updateUser
      summary: Update a specific user (full update)
      description: >-
        This endpoint is used to update a user identified by the userId path
        parameter. To call this endpoint, an access token having the scope
        'SCIM:user:put' is required.
    delete:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: userId
          description: The unique identifier of the user to be removed
          in: path
          required: true
          type: string
      responses:
        '200':
          description: User successfully removed.
        '204':
          description: No Content
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
        '404':
          description: User with specified id does not exist.
          schema:
            $ref: '#/definitions/ScimErrorResource'
      security:
        - OAuth2:
            - 'SCIM:user:delete'
      operationId: removeUser
      summary: Delete user
      description: >-
        This endpoint is used to delete a user identified by the userId path
        parameter. To be able to call this endpoint, an access token having the
        scope 'SCIM:user:delete' is required.
    patch:
      consumes:
        - application/vnd.iwelcome-v2.0+json
      produces:
        - application/vnd.iwelcome-v2.0+json
      tags:
        - Users
      parameters:
        - name: userId
          description: Identifider of the user to update
          in: path
          required: true
          type: string
        - name: userMap
          description: Object with patch attribute names and values
          schema:
            $ref: '#/definitions/MapOfStringsAndObjects'
          in: body
          required: true
      responses:
        '200':
          description: User successfully updated.
          schema:
            $ref: '#/definitions/User'
        '204':
          description: No Content
        '400':
          description: Invalid parameters. Validation failed.
          schema:
            $ref: '#/definitions/ScimErrorResource'
        '401':
          description: This error code is returned when the access token is not valid.
          schema:
            $ref: '#/definitions/UnauthorizedErrorResponse'
        '403':
          description: >-
            This error code is returned when the access token is valid, but it
            does not have the required scope attached to it.
          schema:
            $ref: '#/definitions/ForbiddenErrorResponse'
      security:
        - OAuth2:
            - 'SCIM:user:patch'
      operationId: patchUser
      summary: Update a specific user (partial update)
      description: >-
        The endpoint is used to partially update a user identified by the userId
        path parameter. In order to be able to call this endpoint, an access
        token having the scope 'SCIM:user:patch' is required.
definitions:
  User:
    type: object
    additionalProperties:
      type: object
  UsersDTO:
    properties:
      users:
        type: array
        items:
          $ref: '#/definitions/User'
      itemsPerPage:
        format: int32
        description: >-
          Specifies the number of search results returned in a query response
          page.
        type: integer
      schemas:
        type: array
        items:
          type: string
      startIndex:
        format: int32
        description: The index of the first result in the current set of search results.
        type: integer
      totalResults:
        format: int64
        description: Specifies the total number of results matching the query.
        type: integer
  MapOfStringsAndObjects:
    type: object
    additionalProperties:
      type: object
  ScimErrorResource:
    required:
      - schemas
      - status
    type: object
    properties:
      schemas:
        description: >-
          The resource type's primary/base schema URI, e.g.,
          "urn:ietf:params:scim:schemas:core:1.0:User".  This MUST be equal to
          the "id" attribute of the associated "Schema" resource.
        type: array
        items:
          enum:
            - 'urn:ietf:params:scim:api:messages:2.0:Error'
          type: string
      status:
        description: >-
          The HTTP status code (see Section 6 of
          [RFC7231](https://tools.ietf.org/html/rfc7231#section-6)) expressed as
          a JSON string.
        type: string
      scimType:
        description: >-
          A SCIM detail error keyword.

          * invalidFilter - The specified filter syntax was invalid, or the
          specified attribute and filter comparison combination is not
          supported.

          * tooMany - The specified filter yields many more results than the
          server is willing to calculate or process.  For example, a filter such
          as "(userName pr)" by itself would return all entries with a
          "userName" and MAY not be acceptable to the service provider.

          * uniqueness - One or more of the attribute values are already in use
          or are reserved.

          * mutability - The attempted modification is not compatible with the
          target attribute's mutability or current state (e.g., modification of
          an "immutable" attribute with an existing value).

          * invalidSyntax - The request body message structure was invalid or
          did not conform to the request schema.

          * invalidPath - The "path" attribute was invalid or malformed.

          * noTarget - The specified "path" did not yield an attribute or
          attribute value that could be operated on.  This occurs when the
          specified "path" value contains a filter that yields no match.

          * invalidValue - A required value was missing, or the value specified
          was not compatible with the operation or attribute type (see Section
          2.2 of [RFC7643](https://tools.ietf.org/html/rfc7643)), or resource
          schema (see Section 4 of
          [RFC7643](https://tools.ietf.org/html/rfc7643)).

          * invalidVers - The specified SCIM protocol version is not supported.

          * sensitive - The specified request cannot be completed, due to the
          passing of sensitive (e.g., personal) information in a request URI. 
          For example, personal information SHALL NOT be transmitted over
          request URIs.
        enum:
          - invalidFilter
          - tooMany
          - uniqueness
          - mutability
          - invalidSyntax
          - invalidPath
          - noTarget
          - invalidValue
          - invalidVers
          - sensitive
        type: string
      detail:
        description: A detailed human-readable message.
        type: string
  UnauthorizedErrorResponse:
    type: object
    properties:
      errorCode:
        type: string
      message:
        type: string
      description:
        type: string
  ForbiddenErrorResponse:
    type: object
    properties:
      error_code:
        type: string
      message:
        type: string
      description:
        type: string
securityDefinitions:
  OAuth2:
    flow: accessCode
    authorizationUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/authorize'
    tokenUrl: 'https://example-domain-uri.com/auth/oauth2.0/v1/token'
    scopes:
      'SCIM:user:get': Allows to retrieve user attributes
      'SCIM:user:post': Allows to create a new user
      'SCIM:user:query': Allows to get multiple users
      'SCIM:user:put': Allows to update user's attributes
      'SCIM:user:patch': Allows a partial update of a user's attributes
      'SCIM:user:delete': Allows to delete users
    type: oauth2
tags:
  - name: Users
    description: SCIM Users
