Clarivate Administration - User data API

openapi: 3.2.0
info:
  title: Converis Web Services Administration - User data API
  description: This API Specification describes how to read data from Converis in order to use it in other systems.
  contact:
    email: converis-info@clarivate.com
  version: '2.0'
servers:
- url: https://api.clarivate.com/converisreadapi
tags:
- name: Administration - User data
  description: Perform User operations
paths:
  /admin/users:
    get:
      tags:
      - Administration - User data
      summary: Get all users
      description: Get all users of your Converis or users with only specific ___role___
      parameters:
      - name: role
        in: query
        description: Filter users only with specific role. Select all roles if null.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: Researcher
      - name: type
        in: query
        description: "Filter users based on their type:\n * ___INTERNAL___ - Converis users that login directly in Converis\n * ___EXTERNAL___ - Login server users that login in Converis through SSO, e.g. Shibboleth\n * ___ALL___ - No filter, i.e. the response contains internal and external users.\n"
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ALL
          enum:
          - INTERNAL
          - EXTERNAL
          - ALL
      - name: startRecord
        in: query
        description: Starting record.
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: count
        in: query
        description: Number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: getAdminUsers
      x-operation-id-source: derived
    post:
      tags:
      - Administration - User data
      summary: Create user
      description: Create a Converis user with roles. An email will be sent to the INTERNAL users with the autogenerated password.
      requestBody:
        description: A user to be created
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              userName: first.last
              firstName: First
              lastName: Last
              email: first.last@example-university.edu
              firstLogin: true
              preferredLanguage: en_GB
              active: true
              acceptedTC: false
              userType: INTERNAL
              roles:
              - roleName: Researcher
                entryPointId: 123124324
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
              example:
                timestamp: '2017-07-21T17:32:28Z'
                path: /converis-apis/ws/v2/admin/users
                status: 201
                statusDescription: Created
                message: User first.last successfully created.
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: postAdminUsers
      x-operation-id-source: derived
  /admin/users/{username}:
    get:
      tags:
      - Administration - User data
      summary: Get information of a specific user
      description: Get information of a specific user by ___username___
      parameters:
      - name: username
        in: path
        description: the username which is used to login in Converis
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: getAdminUsersByUsername
      x-operation-id-source: derived
    put:
      tags:
      - Administration - User data
      summary: Update user
      description: 'Update a specific user by ___username___. If roles are not provided in request body, then they remain unchanged, otherwise they will be overwritten.

        Please note that username can''t be changed and is not allowed in request body'
      parameters:
      - name: username
        in: path
        description: the username which is used to login in Converis
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: A user to be updated. If roles are not provided in request body, then they remain unchanged, otherwise they will be overwritten.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              firstName: First
              lastName: Last
              email: first.last@example-university.edu
              firstLogin: true
              preferredLanguage: en_GB
              active: true
              acceptedTC: false
              userType: INTERNAL
              roles:
              - roleName: Researcher
                entryPointId: 123124324
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
              example:
                timestamp: '2017-07-21T17:32:28Z'
                path: /converis-apis/ws/v2/admin/users/first.last
                status: 200
                statusDescription: Ok
                message: User first.last successfully updated.
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: putAdminUsersByUsername
      x-operation-id-source: derived
    delete:
      tags:
      - Administration - User data
      summary: Delete user
      description: Delete a specific user and its roles by ___username___.
      parameters:
      - name: username
        in: path
        description: The username that is used to login in Converis. A user can be internal or external user, i.e. logged in through SSO, e.g. Shibboleth
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
              example:
                timestamp: '2017-07-21T17:32:28Z'
                path: /converis-apis/ws/v2/admin/users/first.last
                status: 200
                statusDescription: Ok
                message: User first.last successfully deleted.
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: deleteAdminUsersByUsername
      x-operation-id-source: derived
components:
  schemas:
    User:
      type: object
      properties:
        userName:
          type: string
          maxLength: 255
          example: loginname
          description: It is required only for POST create user.
        firstName:
          type: string
          maxLength: 255
          example: First
        lastName:
          type: string
          maxLength: 255
          example: last
        email:
          type: string
          format: email
          example: first.last@converis.clarivate.com
          description: For internal users, a notification with password will be sent to the email.
        firstLogin:
          type: boolean
          example: true
        preferredLanguage:
          type: string
          example: en_GB
        active:
          type: boolean
          example: true
        acceptedTC:
          type: boolean
          example: true
        userType:
          type: string
          enum:
          - INTERNAL
          - EXTERNAL
          example: INTERNAL
          description: INTERNAL users are the users which directly login in Converis. External users are the users that login through SSO, e.g. Shibboleth
        lastLogin:
          type: string
          description: The date-time notation as defined by RFC 3339, section 5.6, e.g. "2017-07-21T17:32:28"
          format: date-time
        roles:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
    DefaultResponse:
      required:
      - statusDescirption
      - message
      - path
      - status
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: The date-time notation as defined by RFC 3339, section 5.6, e.g. "2017-07-21T17:32:28Z"
          format: date-time
        path:
          type: string
          description: The path which is used by user, e.g./converis-apis/ws/v2/data/entities/Publication
          format: uri
        status:
          type: integer
          description: HTTP Status code,e.g. 400+
          example: 400
        statusDescription:
          type: string
          description: Description of HTTP Status code, e.g. Bad Request
          example: Bad Request
        message:
          type: string
          description: The detailed description of the error
    UserList:
      required:
      - count
      - data
      - nrRecordsAll
      - nrRecordsFound
      - startRecord
      type: object
      properties:
        startRecord:
          type: integer
          example: 1
          description: only for GET response
        count:
          type: integer
          example: 50
          description: only for GET response
        nrRecordsAll:
          type: integer
          example: 1540
          description: only for GET response
        nrRecordsFound:
          type: integer
          example: 50
          description: only for GET response
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
    UserRole:
      properties:
        roleName:
          type: string
          description: 'Converis user role - Please carefully check your Converis configuration. Do not provide names of the specific language. Special role names for admins can be used: Config Admin or Super Admin. For special roles no entryPointId is needed.'
          example: Researcher
        entryPointId:
          type: integer
          format: int64
          description: User entry point
          example: 123456
        entryPointDataUrl:
          type: string
          description: The entrypoint data url - only by GET Request
          example: /converis-apis/ws/v2/data/entities/Person/123456
        entryPointDefinitionUrl:
          type: string
          description: Entry point definition url - only by GET Request
          example: /converis-apis/ws/v2/config/entities/Person
  securitySchemes:
    BasicAuth:
      type: http
      description: The authentication information has to be provided by the client application as Basic authentication header. This can be configured by an admin in Converis under Configuration -> API Authentication Info.
      scheme: basic