ControlUp User sessions API

openapi: 3.2.0
info:
  title: DaaS IQ User sessions API
  description: 'Multi-cloud Virtual Desktop Infrastructure Management API (Default Version: v1.0)


    🔒 **Authentication**


    This API supports two authentication methods:


    **1. API Key (Bearer Token)** - Recommended for programmatic access

    - Create an API key at [API Key Management](https://support.controlup.com/docs/create-an-api-key)

    - Include in requests: `Authorization: Bearer YOUR_API_KEY`


    **2. Cookie Authentication** - For browser-based access

    - Login via DEX authentication service

    - The `user_dex_token` cookie will be automatically included'
  contact:
    name: ControlUp Support
    url: https://controlup.com/support
    email: support@controlup.com
  version: v1
  x-build-version: 1.0.107
servers:
- url: https://api.controlup.com/daas-iq/v1
tags:
- name: User sessions
paths:
  /cloud/user-sessions/{userSessionId}/actions:
    post:
      tags:
      - User sessions
      summary: Execute an action on a user session
      description: Creates a background job to perform the action (send message, sign out, disconnect). Poll the statusUrl for progress updates.
      operationId: ExecuteUserSessionAction
      parameters:
      - name: userSessionId
        in: path
        description: The unique identifier of the user session.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The action request containing the action type.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSessionActionRequest'
        required: true
      responses:
        '201':
          description: Action job created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreatedDto'
              example:
                id: a1b2c3d4-5678-90ab-cdef-1234567890ab
                jobType: cloudResourceImport
                action: Cloud Resource Import
                jobUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab
                statusUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab/status
                logsUrl: https://api.example.com/api/v1/jobs/a1b2c3d4-5678-90ab-cdef-1234567890ab/logs
                message: Import job created successfully. Poll statusUrl for progress updates.
        '400':
          description: Bad request. Invalid request parameters or action not applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required. No active license for the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden. User does not have permission to manage user sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found. User session does not exist or does not belong to the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable. License status could not be verified. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - CookieAuth: []
components:
  schemas:
    JobCreatedDto:
      required:
      - action
      - id
      - jobType
      - jobUrl
      - logsUrl
      - message
      - statusUrl
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the created job.
          format: uuid
        jobType:
          $ref: '#/components/schemas/JobType'
        action:
          type: string
          description: 'Job action identifier.

            For standard jobs, this matches the JobType formatted with spaces (e.g., "Cloud Resource Import").

            For action jobs, this is the specific action name formatted with spaces (e.g., "Start", "Stop").'
        jobUrl:
          type: string
          description: URL to get full job details (includes parameters).
        statusUrl:
          type: string
          description: 'URL to poll for lightweight status updates (no parameters).

            Poll this endpoint every 2-5 seconds while job is running.'
        logsUrl:
          type: string
          description: URL to get job logs in JSON format.
        message:
          type: string
          description: 'Human-readable message about job creation.

            Example: "Import job created successfully. Poll statusUrl for progress updates."'
      additionalProperties: false
      description: 'Lightweight response returned when a job is created.

        Contains only essential information needed to track the job.

        Use the statusUrl to poll for updates and jobUrl to get full details.'
    UserSessionActionRequest:
      required:
      - actionType
      type: object
      properties:
        actionType:
          $ref: '#/components/schemas/UserSessionActionType'
        messageTitle:
          maxLength: 256
          type:
          - string
          - 'null'
          description: 'The title of the message to send to the user.

            Required for SendMessage action.'
        messageBody:
          maxLength: 1024
          type:
          - string
          - 'null'
          description: 'The body of the message to send to the user.

            Required for SendMessage action.'
      additionalProperties: false
      description: Request to execute an action on a user session.
    JobType:
      enum:
      - cloudResourceImport
      - inventorySync
      - metricCollection
      - costCollection
      - budgetCollection
      - sessionStateCollection
      - sessionHostAction
      - cloudResourceAction
      - cloudCredentialVerification
      - cloudTenantResourceImport
      - masterImageDeploy
      - masterImagePublish
      - masterImageSync
      - masterImageCleanup
      - masterImageVersionDelete
      - masterImagePublishCleanup
      - licenseUsageReport
      - hostPoolOrphanedResourcesCleanup
      - hostPoolCreate
      - hostPoolSessionHostCreate
      - hostPoolSessionHostBatchCreate
      - hostPoolDelete
      type: string
      description: 'Defines the types of background jobs supported by the system.

        Each job type is processed by a specific worker and has its own parameter structure.'
    ErrorResponse:
      required:
      - status
      - title
      - traceId
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem.
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: 'Dictionary of field-specific validation errors (only present for validation failures).

            Key is the field name, value is an array of error messages for that field.'
        traceId:
          type: string
          description: Request ID (cu-request-id) for tracking and debugging purposes.
      additionalProperties: false
      description: 'Standard error body the API returns when a request fails validation or cannot be completed.

        Follows RFC 7807 Problem Details with additional `errors` and `traceId` fields.'
    UserSessionActionType:
      enum:
      - sendMessage
      - signOut
      - disconnect
      type: string
      description: Types of actions that can be performed on a user session.
  securitySchemes:
    BearerAuth:
      type: http
      description: '**API Key Authentication** (Recommended)


        [Learn how to create an API key](https://api.controlup.io/reference/how-to-create-api-keys).'
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      description: '**Cookie Authentication** (Browser use)


        ⚠️ The ''Authorize'' button cannot set cookies due to browser security.


        To authenticate in browser:

        1. Login via DEX authentication service (same browser session)

        2. Or use DevTools Console: `document.cookie = "user_dex_token=YOUR_TOKEN; path=/"`'
      name: user_dex_token
      in: cookie
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-languages:
  - shell
  - powershell
  - node
  - javascript
  - python
  - c
  - clojure
  - cplusplus
  - csharp
  - http
  - go
  - java
  - json
  - kotlin
  - objectivec
  - ocaml
  - php
  - r
  - ruby
  - swift