openapi: 3.2.0
info:
  title: Management Service User API
  version: 1.0.0
  description: Endpoints to manager users
servers:
- url: /airmdrapi
tags:
- name: User
  description: Endpoints to manager users
paths:
  /user:
    post:
      tags:
      - User
      operationId: createUserAPI
      summary: create user
      description: Creates a user in an organization. This action can only be performed by superadmin or admin accounts. An admin cannot create a superadmin in their own organization, but they can create a superadmin in their accessible organizations.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      security:
      - SessionCookie: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: user created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/filter:
    post:
      tags:
      - User
      operationId: filterUsersAPI
      summary: filter users
      description: Filter users by organization ids and user ids accessible to the logged in user. If no filter is provided, all users in all accessible organizations are returned.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: page
        in: query
        required: true
        description: Page number for paginated results.
        schema:
          type: integer
      - name: size
        in: query
        required: true
        description: Number of results per page.
        schema:
          type: integer
      security:
      - SessionCookie: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterUserRequest'
      responses:
        '200':
          description: all users fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchAllUsersResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/logged-in:
    post:
      tags:
      - User
      operationId: filterLoggedInUsersAPI
      summary: filter logged in users
      description: Filter logged in users by organization ids and user ids accessible to the logged in user. If no filter is provided, all users in all accessible organizations are returned.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: page
        in: query
        required: true
        description: Page number for paginated results.
        schema:
          type: integer
      - name: size
        in: query
        required: true
        description: Number of results per page.
        schema:
          type: integer
      security:
      - SessionCookie: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterLoggedInUsersRequest'
      responses:
        '200':
          description: all logged in users fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchAllUsersResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/bulk-delete:
    post:
      tags:
      - User
      operationId: bulkDeleteUsersAPI
      summary: bulk delete users
      description: Bulk delete users in an organization. This action can only be performed by superadmin or admin accounts.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      security:
      - SessionCookie: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id_list:
                  type: array
                  items:
                    type: string
                  description: The list of user IDs that need to deleted.
      responses:
        '200':
          description: users deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUsersResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/{user_id}:
    get:
      tags:
      - User
      operationId: fetchUserAPI
      summary: fetch user details
      description: Fetches details of a user. This action can only be performed by superadmin or admin accounts; however, users can view their own details regardless of their role.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: user_id
        in: path
        description: The ID of User
        required: true
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: user details fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchUserResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - User
      operationId: updateUserAPI
      summary: update user details
      description: Updates the details of a user. First name, last name, and preferred name can be updated by any user. Role can only be updated by admin or superadmin accounts; however, admins are not permitted to assign superadmin role to a user.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: user_id
        in: path
        description: The ID of User
        required: true
        schema:
          type: string
      security:
      - SessionCookie: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: user details updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - User
      operationId: deleteUserAPI
      summary: delete user
      description: Deletes a user. A user cannot delete their own account. This action can only be performed by superadmin or admin accounts; however, an admin cannot delete a superadmin.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: user_id
        in: path
        description: The id of User
        required: true
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: user deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUsersResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/email/{email_id}:
    get:
      tags:
      - User
      operationId: fetchUserFromEmailAPI
      summary: fetch user details from email
      description: Fetches details of a user with given email.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: email_id
        in: path
        description: The email of User to be fetched
        required: true
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: user details fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchUserResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/verify/bulk:
    post:
      tags:
      - User
      operationId: verifyEmailAPI
      summary: verify email and domain from email
      description: verify if user exists for a given email and organization exists for domain in the email.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
        schema:
          type: string
      security:
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailsRequest'
      responses:
        '200':
          description: verified email and domain successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{user_id}/feature-permissions:
    post:
      tags:
      - User
      operationId: filterFeaturePermissionsAPI
      summary: filter feature permissions
      description: Filters feature permissions for a user.
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: user_id
        in: path
        description: The ID of User
        required: true
        schema:
          type: string
      security:
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterFeaturePermissionsRequest'
      responses:
        '200':
          description: feature permissions fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterFeaturePermissionsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UserRole:
      type: string
      description: role of the user. A <b>user</b> can view data in accessible organizations but cannot create or modify organizations or user accounts. An <b>admin</b> can view data and manage users in accessible organizations but cannot create or modify organizations. A <b>superadmin</b> can view data, manage users, and manage descendant organizations in their accessible organizations.
      enum:
      - user
      - admin
      - superadmin
      x-enum-varnames:
      - UserRoleUser
      - UserRoleAdmin
      - UserRoleSuperAdmin
    Organization:
      type: object
      required:
      - organization_id
      - name
      - code
      - contact_email
      - can_have_child_organizations
      - created_at
      - created_by
      - modified_at
      properties:
        organization_id:
          type: string
          description: unique id of the organization
        name:
          type: string
          description: name of the organization
        code:
          type: string
          description: code of the organization
        contact_email:
          type: string
          description: contact email of the organization
        updates_email:
          type: string
          description: email for sending updates to organization's customer
        parent_organization_id:
          type: string
          description: id of the parent organization
        parent_organization:
          $ref: '#/components/schemas/OrganizationMinimal'
          description: parent organization
        updates_email_for_escalations_from_parent:
          type: array
          items:
            type: string
          description: list of email addresses to notify when case is escalated from parent organization
        can_have_child_organizations:
          type: boolean
          description: flag indicating whether the new organization can further have child organizations
        parent_has_access_to_descendants:
          type: boolean
          description: whether parent organization has access to descendant organizations of the created organization
        parent_has_access:
          type: boolean
          description: whether parent organization has access to organization's entities. Default is True. If False, parent will also not have access to descendants
        updates_email_for_escalations_from_children:
          type: array
          items:
            type: string
          description: list of email addresses to notify when case is escalated from child organizations
        host_url:
          type: string
          description: host url of the organization
        logo_url:
          type: string
          description: url of the organization's logo
        metadata:
          type: object
          description: additional metadata of the organization
          additionalProperties:
            type: string
        features:
          type: array
          items:
            $ref: '#/components/schemas/AirMDRFeature'
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        created_at:
          type: integer
          format: int64
          description: creation time of organization
        created_by:
          type: string
          description: unique id of the user who created the organization
        modified_at:
          type: integer
          format: int64
          description: modified time of organization
    UserFeaturePermission:
      type: object
      required:
      - feature_id
      - user_id
      properties:
        user_id:
          type: string
          description: The ID of the user
        feature_id:
          type: string
          description: The ID of the feature
        can_read_permission_granted_by:
          type: array
          items:
            type: string
          description: The list of user IDs who granted the read permission
        can_write_permission_granted_by:
          type: array
          items:
            type: string
          description: The list of user IDs who granted the write permission
    UserGroupMinimal:
      type: object
      required:
      - user_group_id
      - name
      - type
      properties:
        user_group_id:
          type: string
        name:
          type: string
        type:
          type: string
    FetchAllUsersResponse:
      type: object
      required:
      - data
      - message
      - total
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer
    User:
      type: object
      required:
      - user_id
      - first_name
      - last_name
      - email
      - parent_organization
      - role
      - status
      properties:
        user_id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        preferred_name:
          type: string
        email:
          type: string
        password:
          type: string
        parent_organization:
          $ref: '#/components/schemas/OrganizationMinimal'
        created_at:
          type: integer
          format: int64
        created_by:
          type: string
        status:
          $ref: '#/components/schemas/UserStatus'
        role:
          $ref: '#/components/schemas/UserRole'
        features:
          type: array
          items:
            $ref: '#/components/schemas/AirMDRFeature'
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        user_groups:
          type: array
          items:
            $ref: '#/components/schemas/UserGroupMinimal'
        last_login:
          type: integer
          format: int64
        is_internal:
          type: boolean
          description: Whether user belongs to airmdr organization or not
    FetchUserResponse:
      type: object
      required:
      - data
      - message
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/User'
    Permission:
      type: object
      required:
      - permission_id
      - name
      properties:
        permission_id:
          type: string
        name:
          type: string
        description:
          type: string
    FilterFeaturePermissionsRequest:
      type: object
      properties:
        accessible_organization_ids:
          type: array
          items:
            type: string
          description: The list of organization IDs for which feature permissions are needed.
        feature_identifier:
          type: string
          description: The identifier of the feature for which feature permissions are needed.
        operation:
          $ref: '#/components/schemas/ValidateFeaturePermissionsAction'
    ValidateFeaturePermissionsAction:
      type: string
      enum:
      - read
      - write
      x-enum-varnames:
      - ValidateFeaturePermissionsActionRead
      - ValidateFeaturePermissionsActionWrite
    CreateUserResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/User'
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: user friendly error message
    SortOrder:
      type: integer
      enum:
      - 0
      - 1
      x-enum-varnames:
      - Asc
      - Desc
    UpdateUserRequest:
      type: object
      properties:
        first_name:
          type: string
          description: first name of the user
        last_name:
          type: string
          description: last name of the user
        preferred_name:
          type: string
          description: preferred name of the user
        role:
          $ref: '#/components/schemas/UserRole'
    FilterFeaturePermissionsResponse:
      type: object
      required:
      - data
      - message
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserFeaturePermission'
        operation_allowed:
          type: boolean
          description: Whether the operation is allowed for the given feature permissions.
    UpdateUserResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/User'
    SortFields:
      type: object
      required:
      - field
      - sort_order
      properties:
        field:
          type: string
          description: indicates which field will be used for sorting
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: indicates sort order - asc or desc
    VerifyEmailsResponse:
      type: object
      required:
      - data
      - message
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/VerifyEmailResponse'
    FilterUserRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/ListUserFilter'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SortFields'
    UserStatus:
      type: string
      description: user account status
      enum:
      - active
      - pending
      - disabled
      - deleted
      - password_reset_required
      x-enum-varnames:
      - UserStatusActive
      - UserStatusPending
      - UserStatusDisabled
      - UserStatusDeleted
      - UserStatusPasswordResetRequired
    FilterLoggedInUsersRequest:
      type: object
      properties:
        accessible_organization_list:
          type: array
          items:
            type: string
          description: The list of organization IDs for which user information is needed.
    AirMDRFeature:
      type: object
      required:
      - feature_id
      - name
      properties:
        feature_id:
          type: string
          description: The id of the feature
        name:
          type: string
          description: The name of the feature
        description:
          type: string
          description: The description of the feature
    DeleteUsersResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    403Error:
      type: object
      properties:
        message:
          type: string
          const: User does not have permission to perform this action
    CreateUserRequest:
      type: object
      required:
      - email
      - organization_id
      properties:
        first_name:
          type: string
          description: first name of the user
        last_name:
          type: string
          description: last name of the user
        preferred_name:
          type: string
          description: preferred name of the user
        email:
          type: string
          description: email address of the user
        password:
          type: string
          description: password to set for the account
        organization_id:
          type: string
          description: id of the organization in which the user needs to be added
        role:
          $ref: '#/components/schemas/UserRole'
    ListUserFilter:
      type: object
      properties:
        search:
          type: string
          description: search key for user name or email
        organization_id_list:
          type: array
          items:
            type: string
          description: The list of organization IDs for which user information is needed.
        user_id_list:
          type: array
          items:
            type: string
          description: The list of user IDs for which user information is needed.
        email_id_list:
          type: array
          items:
            type: string
          description: The list of email IDs for which user information is needed.
        status_list:
          type: array
          items:
            $ref: '#/components/schemas/UserStatus'
          description: The list of user status for which user information is needed.
        role_list:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: The list of user roles for which user information is needed.
        never_logged_in:
          type: boolean
          description: Fetch users who have never logged into the system.
        created_by:
          type: array
          description: The list of users uuids who created users
          items:
            type: string
        only_logged_in_users:
          type: boolean
          description: Fetch only logged in users.
        exclude_system_users:
          type: boolean
          description: Fetch only users who are not system users.
        accessible_organization_list:
          type: array
          description: The list of organization IDs for which user information is needed.
          items:
            type: string
        include_child_users_with_org_context_access:
          type: boolean
          description: Fetch users who have access to the organization context.
    OrganizationMinimal:
      type: object
      required:
      - organization_id
      - name
      - code
      - sso_enabled
      properties:
        organization_id:
          type: string
          description: unique id of the organization
        name:
          type: string
          description: name of the organization
        code:
          type: string
          description: code of the organization
        logo_url:
          type: string
          description: url of the organization's logo
        sso_enabled:
          type: boolean
          description: flag indicating whether sso is enabled for the organization
    VerifyEmailResponse:
      type: object
      required:
      - email_id
      properties:
        email_id:
          type: string
        user:
          $ref: '#/components/schemas/User'
        organization:
          $ref: '#/components/schemas/Organization'
    VerifyEmailsRequest:
      type: object
      required:
      - email_ids
      properties:
        email_ids:
          type: array
          items:
            type: string
  parameters:
    organization-id:
      name: Organization-ID
      in: header
      description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
    x-request-id:
      name: X-Request-ID
      in: header
      description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
    user-id:
      name: User-ID
      in: header
      description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: Session
x-tagGroups:
- name: Included APIs
  tags:
  - Organization
  - User
  - User Group
  - Token
  - Permission