/password/{email}:
  post:
    tags:
    - password
    description: Submit password reset for a given email.
    operationId: requestResetPassword
    parameters:
    - name: email
      in: path
      required: true      
      description: User email for reseting password
      schema:
        type: string
    responses:
      '200':
        description: successfylly send reset password email to user
      '404':
        description: email could not be found OR account is not active
/password/id/{resetPasswordId}:
  get:
    tags:
    - password
    description: Get a password reset request, this should be called when user click on forgot password link from email
    operationId: getResetPasswordRequest
    parameters:
    - name: resetPasswordId
      in: path      
      required: true
      description: Reset password request id, this normally is taken from the reset password email
      schema:
        type: string
    responses:
      200:
        description: the request is valid, user can now reset their password
      400:
        description: the request is either expired or invalid
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateResponse'
      404:
        description: the request is not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateResponse'
  post:
    tags:
    - password
    description: Submit a new password for the corresponding request.
    operationId: setPassword
    parameters:
    - name: resetPasswordId
      in: path      
      required: true
      description: Reset password request id, this normally is taken from the reset password email
      schema:
        type: string
    requestBody:
      required: true
      content:
        application/json: 
          schema: 
            $ref: '#/components/schemas/ChangePasswordRequest'
    responses:
      200:
        description: password is reset successfully
      400:
        description: request is either expired, invalid OR password is missing from request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateResponse'
      404:
        description: the request is not found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateResponse'