openapi: 3.0.3
info:
  title: ExtremeCloud IQ Account User API
  description: 'ExtremeCloud IQ™ API allows customers and partners to create solutions for the management, monitoring, and provisioning

    of any ExtremeCloud IQ™ environment.


    All related resources and documentation are available at [ExtremeCloud IQ Developer Portal](https://developer.extremecloudiq.com/).

    Please check [Get Started and Tutorial](https://developer.extremecloudiq.com/documentation/) to understand how to use the APIs.


    Get the [latest OpenAPI definition](https://github.com/extremenetworks/ExtremeCloudIQ-OpenAPI/blob/main/xcloudiq-openapi.yaml)

    from [ExtremeCloud IQ OpenAPI GitHub repository](https://github.com/extremenetworks/ExtremeCloudIQ-OpenAPI).


    Please have a valid [ExtremeCloud IQ](https://extremecloudiq.com/) account before getting started.

    If you don''t have one, please [register a new account](https://www.extremenetworks.com/cloud-networking/).'
  termsOfService: https://www.extremenetworks.com/company/legal/terms-of-use/
  contact:
    name: Extreme Networks Support
    url: https://www.extremenetworks.com/support
    email: support@extremenetworks.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 25.9.0-36
servers:
- url: https://api.extremecloudiq.com
  description: ExtremeCloud IQ REST API Server
tags:
- name: User
  description: Local and external user management in ExtremeCloud IQ account
paths:
  /users:
    get:
      tags:
      - User
      summary: List all users
      description: List users with pagination.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_user_list
      operationId: listUsers
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedXiqUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    post:
      tags:
      - User
      summary: Create new user
      description: Create a new user to access.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_create_new_user
      operationId: createUser
      requestBody:
        description: Create new user request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqCreateUserRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/me:
    get:
      tags:
      - User
      summary: Get current user info
      description: Get currently login user info.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_current_user
      operationId: getCurrentUser
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/{id}:
    get:
      tags:
      - User
      summary: Get user info by ID
      description: Get user info for a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_user
      operationId: getUser
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    patch:
      tags:
      - User
      summary: Update user info
      description: Updates user info for a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_update_user
      operationId: updateUser
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        description: Update user request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqUpdateUserRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    delete:
      tags:
      - User
      summary: Delete user by ID
      description: Delete a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_delete_user
      operationId: deleteUser
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/external:
    get:
      tags:
      - User
      summary: List external access users
      description: List a page of external access users.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_external_user_list
      operationId: listExternalUsers
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedXiqExternalUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    post:
      tags:
      - User
      summary: Grant external access
      description: Grant external access to a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_grant_external_user
      operationId: grantExternalUser
      requestBody:
        description: Grant external user request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqGrantExternalUserRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqExternalUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/external/{id}:
    get:
      tags:
      - User
      summary: Get external access info
      description: Get external access info for a specific external user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_get_external_user
      operationId: getExternalUser
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/XiqExternalUser'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    patch:
      tags:
      - User
      summary: Update external access info
      description: Updates external access info for a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_update_external_user
      operationId: updateExternalUser
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        description: Update external user request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/XiqUpdateExternalUserRequest'
            examples:
              Update_external_user_info.:
                description: Update external user info.
                value:
                  user_role: ADMINISTRATOR
        required: true
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
    delete:
      tags:
      - User
      summary: Revoke external access
      description: Revoke external acccess for a specific user.
      externalDocs:
        description: API Reference
        url: https://extremecloudiq.com/api-docs/api-reference.html#_revoke_external_user
      operationId: revokeExternalUser
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/grid:
    post:
      tags:
      - User
      summary: List users
      description: Returns a paginated list of users with support for search, filter, and sort.
      operationId: list_users
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: search
        in: query
        description: Search term for user name, email or group
        required: false
        schema:
          type: string
      - name: sort_field
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          enum:
          - data_usage
          - session_duration
          - expiration
          - user_name
          - email
          - group
          - source
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user_name:
                  type: array
                  items:
                    type: string
                  description: Filter by user name(s)
                group:
                  type: array
                  items:
                    type: string
                  description: Filter by user group(s)
                email:
                  type: array
                  items:
                    type: string
                  description: Filter by email(s)
                source:
                  type: array
                  items:
                    type: string
                  description: Filter by session source(s)
                status:
                  type: boolean
                  description: Filter by user status
                number_filters:
                  type: array
                  description: 'The number-based column filters available. Available columns: data_usage, session_duration, expiration.

                    '
                  items:
                    $ref: '#/components/schemas/number_filter'
                site_ids:
                  description: List of site IDs to filter the users grid
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: A paginated list of user sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RmPagedUsers'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/filter_metadata:
    post:
      tags:
      - User
      summary: List user grid filter metadata
      description: Returns lists of available values for user_name, group, and source fields used in the user grid.
      operationId: listUserGridFilterMetadata
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                site_ids:
                  description: List of site IDs to filter the users grid
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: Lists of values for user grid filters
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_names:
                    type: array
                    items:
                      type: string
                    description: List of unique user names
                  groups:
                    type: array
                    items:
                      type: string
                    description: List of unique user groups
                  sources:
                    type: array
                    items:
                      type: string
                    description: List of unique session sources
                  emails:
                    type: array
                    items:
                      type: string
                    description: List of unique emails
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/type_distribution:
    post:
      tags:
      - User
      summary: Get user type distribution
      description: Returns the percentage distribution of connected users by type (PPSK, RADIUS, Others) and the total number of connected users.
      operationId: getUserTypeDistribution
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                site_ids:
                  description: List of site IDs to filter the users grid
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: User type distribution and total connected users
          content:
            application/json:
              schema:
                type: object
                properties:
                  ppsk_percentage:
                    type: number
                    format: float
                    description: Percentage of users authenticated via PPSK
                  radius_percentage:
                    type: number
                    format: float
                    description: Percentage of users authenticated via RADIUS
                  others_percentage:
                    type: number
                    format: float
                    description: Percentage of users authenticated via other methods
                  total_connected_users:
                    type: integer
                    description: Total number of connected users
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/data_usage:
    post:
      tags:
      - User
      summary: Get user data usage
      description: Returns data usage in bytes for each user.
      operationId: getUserDataUsage
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                site_ids:
                  description: List of site IDs to filter the users grid
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: Data usage per user
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        user_name:
                          type: string
                          description: Name or identifier of the user
                        data_usage_gb:
                          type: number
                          format: float
                          description: Data usage in bytes
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
  /users/grid_export:
    post:
      tags:
      - User
      summary: Export user grid
      description: Export the user grid data as a CSV file.
      operationId: exportUserGridToCsv
      parameters:
      - name: search
        in: query
        description: Search term for user name, email or group
        required: false
        schema:
          type: string
      - name: sort_field
        in: query
        description: Field to sort by
        required: false
        schema:
          type: string
          enum:
          - data_usage
          - session_duration
          - expiration
          - user_name
          - email
          - group
          - source
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user_name:
                  type: array
                  items:
                    type: string
                  description: Filter by user name(s)
                group:
                  type: array
                  items:
                    type: string
                  description: Filter by user group(s)
                source:
                  type: array
                  items:
                    type: string
                  description: Filter by session source(s)
                email:
                  type: array
                  items:
                    type: string
                  description: Filter by email(s)
                site_ids:
                  description: List of site IDs to filter the client health grid
                  type: array
                  items:
                    type: integer
                    format: int64
                number_filters:
                  type: array
                  description: 'The number-based column filters available. Available columns: data_usage, session_duration, expiration.

                    '
                  items:
                    $ref: '#/components/schemas/number_filter'
      responses:
        '202':
          description: Accepted - The request has been accepted for processing, but the processing has not been completed.
          headers:
            location:
              description: The URL to check the status or download the exported file
              schema:
                type: string
                format: uri
            retry-after:
              description: Time in seconds to wait before polling the status
              schema:
                type: integer
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - BearerAuth: []
components:
  parameters:
    order:
      name: order
      in: query
      description: The sort order (ascending by default)
      required: false
      schema:
        $ref: '#/components/schemas/XiqSortOrder'
    page:
      name: page
      in: query
      description: Page number, min = 1
      required: false
      schema:
        minimum: 1
        type: integer
        format: int32
        default: 1
    startTime:
      name: startTime
      in: query
      description: The start time to query, epoch time in milliseconds since 1/1/1970
      required: true
      schema:
        type: integer
        format: int64
    limit:
      name: limit
      in: query
      description: Page Size, min = 1, max = 100
      required: false
      schema:
        maximum: 100
        minimum: 1
        type: integer
        format: int32
        default: 10
    endTime:
      name: endTime
      in: query
      description: The end time to query, epoch time in milliseconds since 1/1/1970
      required: true
      schema:
        type: integer
        format: int64
    id:
      name: id
      in: path
      description: The unique identifier
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    XiqSortOrder:
      type: string
      enum:
      - ASC
      - DESC
    RmUsers:
      type: object
      properties:
        status:
          type: boolean
          description: The connection status of user
        site:
          type: string
          description: The site where the user is located
        building:
          type: string
          description: The building where the user is located
        floor:
          type: string
          description: The floor where the user is located
        user_name:
          type: string
          description: Name of the user
        email:
          type: string
          description: Email address of the user
        group:
          type: string
          description: Group to which the user belongs
        wireless_clients:
          type: integer
          description: The number of wireless clients
        wired_clients:
          type: integer
          description: The number of wired clients
        data_usage:
          type: integer
          format: int64
          description: Total data usage in bytes
        source:
          type: string
          description: Source of the session (e.g., RADIUS, SAML)
        session_duration:
          type: integer
          format: int64
          description: Duration of the session in seconds
        expiration:
          type: integer
          format: int64
          description: Time in seconds until the session expires
    XiqGrantExternalUserRequest:
      type: object
      required:
      - login_name
      - user_role
      properties:
        login_name:
          type: string
          description: Login name, i.e. username or login Email
        user_role:
          $ref: '#/components/schemas/XiqUserRole'
        org_id:
          type: integer
          description: The HIQ organization ID if it is HIQ user, otherwise leave it as empty
          format: int64
        enable_api_access:
          type: boolean
          description: Whether to enable API access, false by default
    RmPagedUsers:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/RmUsers'
    PagedXiqExternalUser:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/XiqExternalUser'
    XiqUser:
      allOf:
      - $ref: '#/components/schemas/XiqBaseEntity'
      - type: object
        required:
        - login_name
        properties:
          login_name:
            type: string
            description: Login name, i.e. username or login Email
          first_name:
            type: string
            description: The first name
          last_name:
            type: string
            description: The last name, i.e. family name
          display_name:
            type: string
            description: The name to display
          phone:
            type: string
            description: The Phone Number
          job_title:
            type: string
            description: The job title
          locale:
            type: string
            description: The locale
          user_role:
            $ref: '#/components/schemas/XiqUserRole'
          idle_timeout:
            type: integer
            description: The idle timeout in minutes, the minimum value is 5 minutes and the maximum value is 4 hours
            format: int32
          last_login_time:
            type: string
            description: The last login time
            format: date-time
          org_id:
            type: integer
            description: The HIQ organization ID if it is HIQ user
            format: int64
    XiqErrorParams:
      type: object
      description: Error parameters
      properties:
        field:
          type: string
          description: The error field
        value:
          type: string
          description: The error value
    XiqUpdateUserRequest:
      type: object
      properties:
        login_name:
          type: string
          description: Login name, i.e. username or login Email
        display_name:
          type: string
          description: The user name to display
        idle_timeout:
          type: integer
          description: The idle timeout in minutes, the minimum value is 5 minutes and the maximum value is 4 hours
          format: int32
        user_role:
          $ref: '#/components/schemas/XiqUserRole'
    number_filter:
      type: object
      description: If the filter type is between, only then min and max are to be used, else value is to be used.
      properties:
        column_name:
          description: The name of the column being filtered
          type: string
        filter_type:
          description: The type of number filter
          type: string
          enum:
          - eq
          - neq
          - gt
          - gte
          - lt
          - lte
          - bw
          - blank
          - notblank
        value:
          description: The value of the number
          type: integer
          format: int64
        min:
          description: The minimum value of the number
          type: integer
          format: int64
        max:
          description: The maximum value of the number
          type: integer
          format: int64
    XiqExternalUser:
      allOf:
      - $ref: '#/components/schemas/XiqBaseEntity'
      - type: object
        required:
        - login_name
        - user_role
        properties:
          login_name:
            type: string
            description: Login name, i.e. username or login Email
          user_role:
            $ref: '#/components/schemas/XiqUserRole'
          org_id:
            type: integer
            description: The HIQ organization ID if it is HIQ user.
            format: int64
          enable_api_access:
            type: boolean
            description: Whether to enable API access.
    PagedXiqUser:
      allOf:
      - $ref: '#/components/schemas/XiqPage'
      - type: object
        properties:
          data:
            type: array
            description: The data in the current page
            items:
              $ref: '#/components/schemas/XiqUser'
    XiqBaseEntity:
      required:
      - id
      - create_time
      - update_time
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier
          format: int64
        create_time:
          type: string
          description: The create time
          format: date-time
        update_time:
          type: string
          description: The last update time
          format: date-time
    XiqError:
      type: object
      properties:
        error_code:
          type: string
          description: The error code
        error_id:
          type: string
          description: The error ID for internal troubleshooting
        error_message:
          type: string
          description: The error detailed message
        error_message_code:
          type: string
          description: The error message code
        error_message_description:
          type: string
          description: The error message description
        error_params:
          $ref: '#/components/schemas/XiqErrorParams'
      required:
      - error_code
      - error_id
      - error_message
    XiqPage:
      required:
      - count
      - page
      - total_count
      - total_pages
      type: object
      properties:
        page:
          type: integer
          description: The current page number
          format: int32
        count:
          type: integer
          description: The element count of the current page
          format: int32
        total_pages:
          type: integer
          description: The total page number based on request page size
          format: int32
        total_count:
          type: integer
          description: The total element count
          format: int64
    XiqUpdateExternalUserRequest:
      type: object
      properties:
        user_role:
          $ref: '#/components/schemas/XiqUserRole'
        org_id:
          type: integer
          description: The HIQ organization ID if it is HIQ user, otherwise leave it as empty.
          format: int64
        enable_api_access:
          type: boolean
          description: Whether to enable API access, false by default.
    XiqCreateUserRequest:
      type: object
      required:
      - login_name
      - display_name
      - user_role
      properties:
        login_name:
          type: string
          description: Login name, i.e. username or login Email
        display_name:
          type: string
          description: The user name to display
        idle_timeout:
          type: integer
          description: The idle timeout in minutes, the minimum value is 5 minutes and the maximum value is 4 hours
          format: int32
        user_role:
          $ref: '#/components/schemas/XiqUserRole'
    XiqUserRole:
      type: string
      description: The user administrative role.
      enum:
      - ADMINISTRATOR
      - OPERATOR
      - MONITOR
      - HELP_DESK
      - GUEST_MANAGEMENT
      - OBSERVER
      - INSTALLER
      - APPLICATION_OPERATOR
  responses:
    ErrorResponse:
      description: The generic ExtremeCloud IQ API error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/XiqError'
  securitySchemes:
    BearerAuth:
      type: http
      description: JSON Web Token (JWT) based authentication
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: API Reference
  url: https://extremecloudiq.com/api-docs/api-reference.html