openapi: 3.0.1
info:
  title: Evolution Foundation - Auth Service - Users
  description: Authentication and user and account management
  version: v1.0.0
servers:
- url: https://api.evoai.app
  description: Production server
- url: http://localhost:3001
  description: Development server
  variables:
    port:
      default: '3001'
- url: '{customUrl}'
  description: Custom server
  variables:
    customUrl:
      default: https://your-instance.com
      description: Enter your server URL
paths:
  /api/v1/users:
    get:
      summary: List users
      description: Retrieve a paginated list of users for the current account (requires account-id header)
      operationId: listUsers
      security:
      - ApiAccessTokenAuth: []
      parameters:
      - name: account-id
        in: header
        description: Account ID (required)
        required: true
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        description: Page number
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        description: Items per page
        example: 25
        schema:
          type: integer
      - name: search
        in: query
        description: Search by name or email
        schema:
          type: string
      - name: role
        in: query
        description: "Filter by role:\n * `administrator` \n * `agent` \n "
        schema:
          type: string
          enum:
          - administrator
          - agent
      - name: status
        in: query
        description: Filter by status
        schema:
          type: string
          enum:
          - active
          - inactive
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid query parameters
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid query parameters
                      details:
                        parameter: role
                        valid_values:
                        - administrator
                        - agent
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.read
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: GET
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: GET
    post:
      summary: Create user
      description: Create a new user for the current account (requires account-id header)
      operationId: createUser
      security:
      - ApiAccessTokenAuth: []
      parameters:
      - name: account-id
        in: header
        description: Account ID (required)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Missing required fields
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: 'Required parameter missing: user'
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.create
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: POST
        '422':
          description: Unprocessable Entity (validation errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_failed:
                  summary: User validation failed
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation failed
                      details:
                      - field: email
                        messages:
                        - has already been taken
                        full_messages:
                        - Email has already been taken
                      - field: password
                        messages:
                        - is too short (minimum is 8 characters)
                        full_messages:
                        - Password is too short (minimum is 8 characters)
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: POST
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users
                      method: POST
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserDto'
  /api/v1/users/bulk_create:
    post:
      summary: Bulk create users
      description: Create multiple users for current account (requires account-id header)
      operationId: bulkCreateUsers
      security:
      - ApiAccessTokenAuth: []
      parameters:
      - name: account-id
        in: header
        description: Account ID (required)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Users created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Number of users created
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                  message:
                    type: string
                    example: Users bulk created successfully
              examples:
                success:
                  summary: Users bulk created successfully
                  value:
                    success: true
                    data:
                      count: 1
                    meta:
                      timestamp: '2026-02-03T17:55:11Z'
                    message: Users bulk created successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Missing required fields or invalid emails array
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request parameters
                      details:
                        parameter: emails
                        message: emails array is required
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/bulk_create
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/bulk_create
                      method: POST
        '402':
          description: Payment Required (limite da conta excedido)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                account_limit_exceeded:
                  summary: Account limit exceeded
                  value:
                    success: false
                    error:
                      code: OPERATION_FAILED
                      message: Account limit exceeded. Please purchase more licenses
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/bulk_create
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.bulk_operations
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/bulk_create
                      method: POST
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/bulk_create
                      method: POST
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
              required:
              - emails
  /api/v1/users/check_permission:
    post:
      summary: Check user permission
      description: Check if current user has a specific permission
      operationId: checkUserPermission
      security:
      - ApiAccessTokenAuth: []
      responses:
        '200':
          description: Permission check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      permission_key:
                        type: string
                        format: uuid
                      has_permission:
                        type: boolean
                      is_super_admin:
                        type: boolean
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                  message:
                    type: string
              examples:
                success:
                  summary: Permission granted
                  value:
                    success: true
                    data:
                      permission_key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      has_permission: true
                      is_super_admin: true
                    meta:
                      timestamp: '2026-02-03T17:48:29Z'
                    message: Permission granted
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_permission_key:
                  summary: Permission key is required
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Permission key is required
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/check_permission
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/check_permission
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.read
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/check_permission
                      method: POST
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/check_permission
                      method: POST
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                permission_key:
                  type: string
              required:
              - permission_key
  /api/v1/users/permissions:
    get:
      summary: Get user permissions
      description: Get global permissions for current user
      operationId: getUserPermissions
      security:
      - ApiAccessTokenAuth: []
      responses:
        '200':
          description: Permissions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      permissions:
                        type: array
                        items:
                          type: string
                      role_data:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          key:
                            type: string
                          name:
                            type: string
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                  message:
                    type: string
              examples:
                success:
                  summary: User permissions retrieved successfully
                  value:
                    success: true
                    data:
                      permissions:
                      - users.read
                      - users.create
                      - users.update
                      - users.delete
                      role_data:
                        id: 8cb4a5d9-51a1-4370-8bc0-33a27960d019
                        key: account_owner
                        name: Account Owner
                    meta:
                      timestamp: '2026-02-03T17:35:21Z'
                    message: User permissions retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid request parameters
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request parameters
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/permissions
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/permissions
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.read
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/permissions
                      method: GET
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/permissions
                      method: GET
  /api/v1/users/{id}:
    parameters:
    - name: id
      in: path
      description: User ID
      required: true
      schema:
        type: string
        format: uuid
    get:
      summary: Get user details
      description: Retrieve detailed information about a specific user
      operationId: getUser
      security:
      - ApiAccessTokenAuth: []
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetailResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid user ID format
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user ID format
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.read
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: GET
        '404':
          description: Not Found (user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: GET
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: GET
    patch:
      summary: Update user
      description: Update user information (requires account-id header)
      operationId: updateUser
      security:
      - ApiAccessTokenAuth: []
      parameters:
      - name: account-id
        in: header
        description: Account ID (required)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid user ID format or missing required fields
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user ID format
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.update
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
        '404':
          description: Not Found (user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
        '422':
          description: Unprocessable Entity (validation errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_failed:
                  summary: Validation failed
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation failed
                      details:
                      - field: email
                        messages:
                        - has already been taken
                        full_messages:
                        - Email has already been taken
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: PATCH
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserDto'
    delete:
      summary: Delete user
      description: Delete a user (soft delete) (requires account-id header)
      operationId: deleteUser
      security:
      - ApiAccessTokenAuth: []
      parameters:
      - name: account-id
        in: header
        description: Account ID (required)
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid user ID format
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user ID format
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: DELETE
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: DELETE
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.delete
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: DELETE
        '404':
          description: Not Found (user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: DELETE
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}
                      method: DELETE
  /api/v1/users/{id}/update_mfa:
    parameters:
    - name: id
      in: path
      description: User ID
      required: true
      schema:
        type: string
        format: uuid
    patch:
      summary: Update user MFA settings
      description: Update user multi-factor authentication settings
      operationId: updateUserMFA
      security:
      - ApiAccessTokenAuth: []
      parameters: []
      responses:
        '200':
          description: MFA settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetailResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid user ID format or missing required fields
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user ID format
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.manage_mfa
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
        '404':
          description: Not Found (user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
        '422':
          description: Unprocessable Entity (validation errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_failed:
                  summary: MFA settings validation failed
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation failed
                      details:
                      - field: mfa_method
                        messages:
                        - is not included in the list
                        full_messages:
                        - Mfa method is not included in the list
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_mfa
                      method: PATCH
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    mfa_method:
                      type: string
                      enum:
                      - disabled
                      - totp
                      - email
                      description: MFA method to enable
                    otp_required_for_login:
                      type: boolean
                      description: Whether OTP is required for login
                  required:
                  - mfa_method
              required:
              - user
  /api/v1/users/{id}/update_password:
    parameters:
    - name: id
      in: path
      description: User ID
      required: true
      schema:
        type: string
        format: uuid
    patch:
      summary: Update user password
      description: Update user password
      operationId: updateUserPassword
      security:
      - ApiAccessTokenAuth: []
      parameters: []
      responses:
        '200':
          description: Password updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid user ID format or missing required fields
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid user ID format
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You are not authorized to perform this action
                      details:
                        action: users.change_password
                        record: User
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
        '404':
          description: Not Found (user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: RESOURCE_NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
        '500':
          description: Internal Server Error (erro interno do servidor)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    success: false
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
        '422':
          description: Unprocessable Entity (validation errors)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                incorrect_current_password:
                  summary: Current password is incorrect
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Current password is incorrect
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
                password_validation_failed:
                  summary: New password validation failed
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Validation failed
                      details:
                      - field: password
                        messages:
                        - is too short (minimum is 8 characters)
                        full_messages:
                        - Password is too short (minimum is 8 characters)
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/users/{id}/update_password
                      method: PATCH
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                  description: Current password for verification
                new_password:
                  type: string
                  description: New password
                  minLength: 8
              required:
              - current_password
              - new_password
components:
  schemas:
    CreateUserDto:
      type: object
      required:
      - name
      - email
      properties:
        name:
          type: string
          description: User full name
          minLength: 1
        email:
          type: string
          format: email
          description: User email address
        password:
          type: string
          description: User password (optional, will be auto-generated if not provided)
          minLength: 8
        role:
          type: string
          enum:
          - administrator
          - agent
          description: User role
        availability:
          type: string
          enum:
          - online
          - offline
          - busy
          description: User availability status
        auto_offline:
          type: boolean
          description: Whether user should be automatically set to offline
        custom_attributes:
          type: object
          additionalProperties: true
          description: Custom user attributes
    ErrorResponse:
      type: object
      required:
      - success
      - error
      - meta
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation failed
            details:
              type: object
              additionalProperties: true
              nullable: true
        meta:
          type: object
          required:
          - timestamp
          - path
          - method
          properties:
            timestamp:
              type: string
              format: date-time
              example: '2024-01-15T10:30:00Z'
            path:
              type: string
              example: /api/v1/super_admin/accounts/123
            method:
              type: string
              example: POST
    SuccessResponse:
      type: object
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          nullable: true
          additionalProperties: true
        message:
          type: string
          example: Operation completed successfully
        meta:
          type: object
          nullable: true
          properties:
            timestamp:
              type: string
              format: date-time
    UpdateUserDto:
      type: object
      properties:
        name:
          type: string
          description: User full name
          minLength: 1
        email:
          type: string
          format: email
          description: User email address
        role:
          type: string
          enum:
          - administrator
          - agent
          description: User role
        availability:
          type: string
          enum:
          - online
          - offline
          - busy
          description: User availability status
        auto_offline:
          type: boolean
          description: Whether user should be automatically set to offline
        password:
          type: string
          description: User password (optional)
          minLength: 8
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        type:
          type: string
          enum:
          - User
          - SuperAdmin
        role:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            key:
              type: string
            name:
              type: string
        pubsub_token:
          type: string
        display_name:
          type: string
          nullable: true
        availability:
          type: string
          enum:
          - online
          - busy
          - offline
        mfa_enabled:
          type: boolean
        confirmed:
          type: boolean
        custom_attributes:
          type: object
          additionalProperties: true
        ui_settings:
          type: object
          additionalProperties: true
        is_super_admin:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    UserDetailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/User'
        message:
          type: string
    UserListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        meta:
          type: object
          properties:
            page:
              type: integer
            per_page:
              type: integer
            total_pages:
              type: integer
            total_count:
              type: integer
        message:
          type: string
    UserResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
        message:
          type: string
  securitySchemes:
    DeviseTokenAuth:
      type: apiKey
      in: header
      name: access-token
      description: Devise Token Auth - requires access-token, client, and uid headers
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    SuperAdminAuth:
      type: apiKey
      in: header
      name: api_access_token
      description: Super Admin authentication token
    ApiAccessTokenAuth:
      type: apiKey
      in: header
      name: api_access_token
      description: API access token authentication