openapi: 3.2.0
info:
  description: REST API for the Clinical Knowledge Manager.
  version: 1.6.0
  title: CKM REST Users API
  contact:
    name: CKM Support
    url: https://oceanehr.atlassian.net/servicedesk/customer/portal/15
    email: ckm@oceaninformatics.com
servers:
- url: /ckm/rest/v1
tags:
- name: Users
  description: Endpoint for user-related services, including creating new users as an admin.
paths:
  /users:
    post:
      tags:
      - Users
      summary: Creates a new user.
      description: ''
      operationId: createUser
      security:
      - basicAuth: []
      - sessionid: []
      responses:
        '201':
          description: Successful creation of the new user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewUser'
            application/xml:
              schema:
                $ref: '#/components/schemas/NewUser'
        '400':
          description: General bad request, such as that the provided user format is invalid (unparsable) or there were fatal validation errors, such as missing mandatory fields. The provided username MUST be in the form firstname.lastname
        '403':
          description: Forbidden to create the user. This error response is used if the session user does not have the necessary permissions to create new CKM users. This error response will also be returned when the username or email address is already used by an existing user or if a user with a matching username who previously unregistered from CKM had contributed to CKM for example in review rounds or discussions. In this case, follow the process in the CKM user interface.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
          application/xml:
            schema:
              $ref: '#/components/schemas/NewUser'
        description: The details for the new user.
        required: true
components:
  schemas:
    NewUser:
      type: object
      required:
      - countryCode
      - email
      - firstName
      - lastName
      - username
      properties:
        username:
          type: string
          example: jane.doe
          description: The username of the user, must be in the form of firstname.lastname - any whitespace needs to be removed.
        firstName:
          type: string
          example: Jane
          description: The first name of the user.
        lastName:
          type: string
          example: Doe
          description: The last name of the user.
        email:
          type: string
          example: jane.doe@openehr.org
          description: A valid email address for the user.
        secondaryEmail:
          type: string
          example: jane.doe@oceanhealthsystems.com
          description: An optional additional recovery email address of the user.
        organisation:
          type: string
          example: My health organisation
          description: The name of the user's organisation.
        countryCode:
          type: string
          example: CA
          description: The (ISO-3166 ALPHA 2) country code for the user.
        stateOfCountry:
          type: string
          example: VIC [use only for countryCode=AU]
          description: 'Only for Australia: the state/territory abbreviation, e.g. VIC. Not used for any other country at present.'
        availableAsReviewer:
          type: boolean
          description: True to assert that the user is available as a reviewer, false to assert that the user is not. If this field is NOT provided at all, the user will be asked to be a reviewer in due course (and can then directly choose applicable Health Domains and Professions from CKM's ontology).
        availableAsTranslator:
          type: boolean
          description: True to assert that the user is available as a translator, false to assert that the user is not. If this field is NOT provided at all, the user will be asked to be a translator in due course depending on server settings (and can then directly choose the languages the user is proficient in).
        hasToActivate:
          type: boolean
          description: True to specify that the user needs to activate the account. An activation email is sent to the user on creation; otherwise a welcome email is sent. Defaults to false.
        password:
          type: string
          example: dsfd$52332!äEW4
          description: The initial password for the user. When an initial password is not provided when creating a new user, a password will be auto-generated by CKM. In this case, the new user can use the Forgot Your Password functionality to retrieve a password.
      xml:
        name: user
      description: Contains the relevant main data used to create a new user in CKM.
  securitySchemes:
    sessionid:
      description: Once the session id is known, it can be used for authentication until expired. The provided session id is used (and validated) on making an actual request.
      type: apiKey
      name: JSESSIONID
      in: header
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentification using the CKM username and password. The provided credentials are used (and validated) on making an actual request.
externalDocs:
  description: Find out more about openEHR and the Clinical Knowledge Manager (CKM)
  url: http://www.openehr.org