Workspaces API

Workspaces represent virtual environments that users can launch and access. Each workspace can be a Linux desktop, Windows RDP session, web application, or secure browser.

Workspace Model

string

Unique workspace identifier (e.g., “ws-sap-neogenesys”)

name

string

Display name of the workspace

type

string

Workspace type: "html5", "rdp", "web", "linux", "browser", "windows", "dev", "admin"

description

string

Detailed description of the workspace and its purpose

image_url

string

Thumbnail image URL for the workspace

status

string

Current status: "available", "running", "stopped", "error"

cpu

string

CPU allocation (e.g., “2 vCPU”, “4 vCPU”)

memory

string

Memory allocation (e.g., “4 GB”, “8 GB”)

storage

string

Storage allocation (e.g., “50 GB”, “100 GB”)

url

string

Connection URL for the workspace (if applicable)

connection_type

string

Connection method: "html5", "web", "vnc", "browser"

requires_netbird

boolean

Whether NetBird VPN connection is required

icon

string

Icon identifier for UI display

List Workspaces

Retrieve all available workspaces for the authenticated user.

curl https://your-domain.com/api/workspaces \
  -H "Authorization: Bearer your-token-here"

Response

[
  {
    "id": "ws-sap-neogenesys",
    "name": "SAP Neogénesys",
    "type": "html5",
    "description": "TSPlus HTML5 Desktop para acceso a SAP. Requiere conexión NetBird activa.",
    "image_url": "https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=400",
    "status": "available",
    "cpu": "4 vCPU",
    "memory": "8 GB",
    "storage": "100 GB",
    "url": "http://tsplus.intranet.neosc/",
    "connection_type": "html5",
    "requires_netbird": true,
    "icon": "sap"
  },
  {
    "id": "ws-remote-desktop",
    "name": "Remote Desktop",
    "type": "rdp",
    "description": "Escritorio remoto Windows via TSPlus HTML5. IP: 10.100.10.152",
    "image_url": "https://images.unsplash.com/photo-1624571409108-e9a41746af53?w=400",
    "status": "available",
    "cpu": "4 vCPU",
    "memory": "8 GB",
    "storage": "100 GB",
    "url": "http://10.100.10.152/",
    "connection_type": "html5",
    "requires_netbird": true,
    "icon": "windows"
  }
]

Default Workspaces

If no workspaces exist in the database, the API automatically initializes 5 default workspaces:

SAP Neogénesys (HTML5) - TSPlus Desktop for SAP access
Remote Desktop (RDP) - Windows remote desktop
1Panel Admin (Web) - Infrastructure admin panel
Linux Desktop (Linux) - Ubuntu 22.04 LTS desktop
Secure Browser (Browser) - Isolated browser environment

Create Workspace

Create a new workspace. Requires admin privileges.

curl -X POST https://your-domain.com/api/workspaces \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Environment",
    "type": "dev",
    "description": "Full-stack development workspace with VSCode",
    "url": "http://dev.example.com",
    "connection_type": "web",
    "requires_netbird": true,
    "cpu": "4 vCPU",
    "memory": "16 GB",
    "storage": "200 GB",
    "image_url": "https://images.unsplash.com/photo-1587620962725-abab7fe55159?w=400",
    "icon": "code"
  }'

Request Body

name

string

required

Workspace display name

type

string

required

Workspace type (e.g., “linux”, “windows”, “browser”, “dev”, “admin”)

description

string

required

Detailed description of the workspace

url

string

Connection URL (defaults to empty string)

connection_type

string

Connection method: “web”, “html5”, “vnc”, “browser” (defaults to “web”)

requires_netbird

boolean

Whether NetBird VPN is required (defaults to true)

cpu

string

CPU allocation (defaults to “2 vCPU”)

memory

string

Memory allocation (defaults to “4 GB”)

storage

string

Storage allocation (defaults to “50 GB”)

image_url

string

Thumbnail image URL (defaults to empty string)

icon

string

Icon identifier (defaults to “default”)

Response

{
  "message": "Workspace created",
  "workspace": {
    "id": "ws-a1b2c3d4",
    "name": "Development Environment",
    "type": "dev",
    "description": "Full-stack development workspace with VSCode",
    "url": "http://dev.example.com",
    "connection_type": "web",
    "requires_netbird": true,
    "cpu": "4 vCPU",
    "memory": "16 GB",
    "storage": "200 GB",
    "status": "available",
    "image_url": "https://images.unsplash.com/photo-1587620962725-abab7fe55159?w=400",
    "icon": "code"
  }
}

Error Responses

403

error

{
  "detail": "Admin access required"
}

Update Workspace

Update workspace configuration. Requires admin privileges.

curl -X PUT https://your-domain.com/api/workspaces/ws-a1b2c3d4 \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "cpu": "8 vCPU",
    "memory": "32 GB",
    "status": "available"
  }'

Request Body

All fields are optional. Only provided fields will be updated.

name

string

Updated workspace name

description

string

Updated description

url

string

Updated connection URL

connection_type

string

Updated connection type

requires_netbird

boolean

Updated NetBird requirement

cpu

string

Updated CPU allocation

memory

string

Updated memory allocation

storage

string

Updated storage allocation

image_url

string

Updated image URL

icon

string

Updated icon identifier

status

string

Updated status (“available”, “running”, “stopped”, “error”)

Response

{
  "message": "Workspace updated",
  "workspace": {
    "id": "ws-a1b2c3d4",
    "cpu": "8 vCPU",
    "memory": "32 GB",
    "status": "available"
    // ... other fields
  }
}

Error Responses

403

error

Admin access required

404

error

{
  "detail": "Workspace not found"
}

Delete Workspace

Delete a workspace. Requires admin privileges.

curl -X DELETE https://your-domain.com/api/workspaces/ws-a1b2c3d4 \
  -H "Authorization: Bearer admin-token"

Response

{
  "message": "Workspace deleted"
}

Error Responses

403

error

Admin access required

404

error

Workspace not found

Launch Workspace

Launch a workspace and create a new session.

curl -X POST https://your-domain.com/api/workspaces/ws-sap-neogenesys/launch \
  -H "Authorization: Bearer your-token-here"

Response

{
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "workspace": {
    "id": "ws-sap-neogenesys",
    "name": "SAP Neogénesys",
    "type": "html5",
    "status": "running",
    // ... other workspace fields
  },
  "stream_url": "/viewer/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "tunnel_status": "encrypted",
  "security": {
    "encrypted_tunnel": true,
    "identity_verified": true,
    "mfa_enforced": true,
    "session_recording": true,
    "no_open_ports": true
  }
}

Automatic Actions

When a workspace is launched:

New session is created with user info
Workspace status is updated to "running"
Audit log entry is created: "launch_workspace" action
Security features are enforced

Error Responses

404

error

{
  "detail": "Workspace not found"
}

Stop Workspace

Stop a running workspace and terminate the session.

curl -X POST https://your-domain.com/api/workspaces/ws-sap-neogenesys/stop \
  -H "Authorization: Bearer your-token-here"

Response

{
  "message": "Workspace stopped successfully"
}

Automatic Actions

When a workspace is stopped:

Active session is marked as "terminated"
Session ended_at timestamp is set
Workspace status is updated to "available"
Audit log entry is created: "stop_workspace" action

Reset Workspaces

Reset all workspaces to default configuration. Requires admin privileges.

curl -X POST https://your-domain.com/api/workspaces/reset \
  -H "Authorization: Bearer admin-token"

Response

{
  "message": "Workspaces reset to defaults",
  "count": 5
}

Automatic Actions

All existing workspaces are deleted
5 default workspaces are recreated
Audit log entry is created: "reset_workspaces" action

Error Responses

403

error

Admin access required

Workspace Types

Type	Description	Example Use Case
`html5`	HTML5-based desktop	TSPlus remote desktop
`rdp`	Remote Desktop Protocol	Windows servers
`web`	Web application	Admin panels, dashboards
`linux`	Linux desktop environment	Ubuntu desktop
`browser`	Isolated browser	Secure web browsing
`windows`	Windows environment	Windows applications
`dev`	Development environment	Code editors, IDEs
`admin`	Administrative tools	System management

Connection Types

Type	Description	Protocol
`html5`	Browser-based HTML5	HTTP/WebSockets
`web`	Direct web access	HTTP/HTTPS
`vnc`	VNC remote desktop	VNC over WebSockets
`browser`	Isolated browser session	Custom protocol

Security Features

All workspace launches enforce:

Encrypted Tunnel: WireGuard VPN via NetBird
Identity Verification: JWT token validation
MFA Enforcement: Based on user settings
Session Recording: All activity logged
No Open Ports: Zero-trust network model

Getting Started

Endpoints

Workspaces

Workspaces API

Workspace Model

List Workspaces

Response

Default Workspaces

Create Workspace

Request Body

Response

Error Responses

Update Workspace

Request Body

Response

Error Responses

Delete Workspace

Response

Error Responses

Launch Workspace

Response

Automatic Actions

Error Responses

Stop Workspace

Response

Automatic Actions

Reset Workspaces

Response

Automatic Actions

Error Responses

Workspace Types

Connection Types

Security Features

Build docs developers (and LLMs) love

Getting Started

Endpoints

​Workspaces API

​Workspace Model

​List Workspaces

​Response

​Default Workspaces

​Create Workspace

​Request Body

​Response

​Error Responses

​Update Workspace

​Request Body

​Response

​Error Responses

​Delete Workspace

​Response

​Error Responses

​Launch Workspace

​Response

​Automatic Actions

​Error Responses

​Stop Workspace

​Response

​Automatic Actions

​Reset Workspaces

​Response

​Automatic Actions

​Error Responses

​Workspace Types

​Connection Types

​Security Features

Build docs developers (and LLMs) love

Workspaces API

Workspace Model

List Workspaces

Response

Default Workspaces

Create Workspace

Request Body

Response

Error Responses

Update Workspace

Request Body

Response

Error Responses

Delete Workspace

Response

Error Responses

Launch Workspace

Response

Automatic Actions

Error Responses

Stop Workspace

Response

Automatic Actions

Reset Workspaces

Response

Automatic Actions

Error Responses

Workspace Types

Connection Types

Security Features