Apache Guacamole REST API

openapi: 3.0.3
info:
  title: Apache Guacamole REST API
  version: "1.6.0"
  description: REST API for managing Apache Guacamole remote desktop gateway including connections, users, user groups, permissions, and active sessions.
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:8080/guacamole
    description: Apache Guacamole Server

tags:
  - name: Authentication
    description: Authentication token management
  - name: Connections
    description: Remote desktop connection management
  - name: Connection Groups
    description: Connection group organization
  - name: Users
    description: User account management
  - name: User Groups
    description: User group management
  - name: Active Connections
    description: Active connection session management
  - name: History
    description: Connection history and audit logs
  - name: Schema
    description: Configuration schema information

paths:
  /api/tokens:
    post:
      operationId: createAuthToken
      summary: Apache Guacamole Create Authentication Token
      description: Authenticate and create a session token for subsequent API calls.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Guacamole username
                  example: guacadmin
                password:
                  type: string
                  description: Guacamole password
                  example: guacadmin
              required: [username, password]
      responses:
        '200':
          description: Authentication successful, token returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
              examples:
                CreateAuthToken200Example:
                  summary: Default createAuthToken 200 response
                  x-microcks-default: true
                  value:
                    authToken: abc123def456abc123def456abc123def456abc123def456abc123def456abc1
                    username: guacadmin
                    dataSource: postgresql
                    availableDataSources:
                      - postgresql
        '403':
          description: Authentication failed
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/connections:
    get:
      operationId: listConnections
      summary: Apache Guacamole List Connections
      description: List all remote desktop connections available to the authenticated user.
      tags:
        - Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier (e.g., postgresql, mysql)
          schema:
            type: string
            example: postgresql
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token from /api/tokens
          schema:
            type: string
      responses:
        '200':
          description: Connections listed successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Connection'
        '403':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createConnection
      summary: Apache Guacamole Create Connection
      description: Create a new remote desktop connection.
      tags:
        - Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connection'
      responses:
        '200':
          description: Connection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '403':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/connections/{connectionId}:
    get:
      operationId: getConnection
      summary: Apache Guacamole Get Connection
      description: Get details of a specific remote desktop connection.
      tags:
        - Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: connectionId
          in: path
          required: true
          description: The unique connection identifier
          schema:
            type: string
            example: "1"
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: Connection retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateConnection
      summary: Apache Guacamole Update Connection
      description: Update an existing remote desktop connection.
      tags:
        - Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: connectionId
          in: path
          required: true
          description: The unique connection identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connection'
      responses:
        '204':
          description: Connection updated successfully
        '404':
          description: Connection not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteConnection
      summary: Apache Guacamole Delete Connection
      description: Delete a remote desktop connection.
      tags:
        - Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: connectionId
          in: path
          required: true
          description: The unique connection identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '204':
          description: Connection deleted successfully
        '404':
          description: Connection not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/users:
    get:
      operationId: listUsers
      summary: Apache Guacamole List Users
      description: List all user accounts in the Guacamole system.
      tags:
        - Users
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: Users listed successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createUser
      summary: Apache Guacamole Create User
      description: Create a new Guacamole user account.
      tags:
        - Users
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/users/{username}:
    get:
      operationId: getUser
      summary: Apache Guacamole Get User
      description: Get details of a specific Guacamole user account.
      tags:
        - Users
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: username
          in: path
          required: true
          description: The username
          schema:
            type: string
            example: guacadmin
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateUser
      summary: Apache Guacamole Update User
      description: Update a Guacamole user account.
      tags:
        - Users
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: username
          in: path
          required: true
          description: The username
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '204':
          description: User updated successfully
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteUser
      summary: Apache Guacamole Delete User
      description: Delete a Guacamole user account.
      tags:
        - Users
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: username
          in: path
          required: true
          description: The username to delete
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '204':
          description: User deleted successfully
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/userGroups:
    get:
      operationId: listUserGroups
      summary: Apache Guacamole List User Groups
      description: List all user groups in the Guacamole system.
      tags:
        - User Groups
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: User groups listed successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/UserGroup'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/activeConnections:
    get:
      operationId: listActiveConnections
      summary: Apache Guacamole List Active Connections
      description: List all currently active remote desktop sessions.
      tags:
        - Active Connections
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: Active connections listed successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ActiveConnection'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/session/data/{dataSource}/history/connections:
    get:
      operationId: listConnectionHistory
      summary: Apache Guacamole List Connection History
      description: List connection history records for audit and reporting.
      tags:
        - History
      parameters:
        - name: dataSource
          in: path
          required: true
          description: The data source identifier
          schema:
            type: string
        - name: Guacamole-Token
          in: header
          required: true
          description: Authentication token
          schema:
            type: string
      responses:
        '200':
          description: Connection history retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectionHistoryEntry'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  schemas:
    AuthToken:
      type: object
      description: Authentication token response from Guacamole login
      properties:
        authToken:
          type: string
          description: Session authentication token
          example: abc123def456
        username:
          type: string
          description: Authenticated username
          example: guacadmin
        dataSource:
          type: string
          description: Default data source identifier
          example: postgresql
        availableDataSources:
          type: array
          description: List of available data source identifiers
          items:
            type: string
          example: [postgresql]

    Connection:
      type: object
      description: Remote desktop connection configuration
      properties:
        identifier:
          type: string
          description: Unique connection identifier
          example: "1"
        name:
          type: string
          description: Human-readable connection name
          example: My RDP Server
        protocol:
          type: string
          description: Remote desktop protocol
          enum: [rdp, vnc, ssh, telnet, kubernetes]
          example: rdp
        parentIdentifier:
          type: string
          description: Parent connection group identifier (ROOT for top-level)
          example: ROOT
        activeConnections:
          type: integer
          description: Number of active sessions for this connection
          example: 0
        parameters:
          type: object
          description: Protocol-specific connection parameters
          additionalProperties:
            type: string

    ConnectionGroup:
      type: object
      description: A group organizing connections and other connection groups
      properties:
        identifier:
          type: string
          description: Unique group identifier
          example: "1"
        name:
          type: string
          description: Group name
          example: Production Servers
        type:
          type: string
          description: Group type (ORGANIZATIONAL or BALANCING)
          enum: [ORGANIZATIONAL, BALANCING]
          example: ORGANIZATIONAL
        parentIdentifier:
          type: string
          description: Parent group identifier
          example: ROOT
        activeConnections:
          type: integer
          description: Total active connections in this group
          example: 3

    User:
      type: object
      description: Guacamole user account
      properties:
        username:
          type: string
          description: Unique username
          example: jsmith
        password:
          type: string
          description: User password (write-only)
          example: securepassword123
        attributes:
          type: object
          description: Additional user attributes
          additionalProperties:
            type: string
        lastActive:
          type: integer
          format: int64
          description: Timestamp of last user activity in milliseconds
          example: 1718153645993

    UserGroup:
      type: object
      description: Guacamole user group for shared permissions
      properties:
        identifier:
          type: string
          description: Unique group identifier
          example: admins
        attributes:
          type: object
          description: Group attributes
          additionalProperties:
            type: string

    ActiveConnection:
      type: object
      description: An active remote desktop session
      properties:
        identifier:
          type: string
          description: Unique active connection identifier
          example: ac-500123
        connectionIdentifier:
          type: string
          description: Associated connection configuration ID
          example: "1"
        username:
          type: string
          description: User who started the session
          example: jsmith
        startDate:
          type: integer
          format: int64
          description: Session start time in milliseconds since epoch
          example: 1718153645993
        remoteHost:
          type: string
          description: IP address of the connecting client
          example: 10.0.0.1

    ConnectionHistoryEntry:
      type: object
      description: Historical record of a completed or active connection
      properties:
        identifier:
          type: string
          description: History entry identifier
          example: hist-500123
        connectionIdentifier:
          type: string
          description: Associated connection ID
          example: "1"
        connectionName:
          type: string
          description: Name of the connection
          example: My RDP Server
        username:
          type: string
          description: Username who made the connection
          example: jsmith
        startDate:
          type: integer
          format: int64
          description: Connection start time in milliseconds
          example: 1718153645993
        endDate:
          type: integer
          format: int64
          description: Connection end time in milliseconds (null if still active)
          example: 1718157245993

  securitySchemes:
    GuacamoleToken:
      type: apiKey
      in: header
      name: Guacamole-Token
      description: Authentication token obtained from POST /api/tokens