{
"openapi": "3.1.0",
"info": {
"title": "Scale-Out Computing on AWS (SOCA) API",
"description": "API specification for SOCA. Add api/doc?ui=swagger or api/doc?ui=rapidoc to change UI provider.",
"version": "1.0.0",
"contact": {
"name": "Open Source AWS Solution",
"url": "https://github.com/awslabs/scale-out-computing-on-aws/tree/main"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0"
}
},
"paths": {
"/api/login_nodes/list": {
"get": {
"operationId": "getLoginNodeIPs",
"tags": [
"Login Nodes"
],
"summary": "List all login node IP addresses",
"description": "Retrieve IP addresses of all running login nodes in the SOCA cluster",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"responses": {
"200": {
"description": "Login node IPs retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "array",
"items": {
"type": "string",
"format": "ipv4",
"description": "IP address of login node (public IP preferred, private IP as fallback)"
},
"example": [
"10.0.1.100",
"52.123.45.67"
]
}
}
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "AWS API error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "AWS API error"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/start": {
"put": {
"operationId": "startVirtualDesktop",
"tags": [
"Virtual Desktops"
],
"summary": "Start virtual desktop",
"description": "Start a stopped DCV virtual desktop session with automatic ODCR (On-Demand Capacity Reservation) management",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the virtual desktop session to start",
"example": "12345678-1234-1234-1234-123456789012"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Desktop start initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your virtual desktop is starting"
}
}
}
}
}
},
"400": {
"description": "Missing parameter or invalid session state",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "This virtual desktop seems to be already running."
}
}
}
}
}
},
"401": {
"description": "Session not found or unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to find this session"
}
}
}
}
}
},
"500": {
"description": "Failed to start desktop or capacity reservation error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to create capacity reservation"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/schedule": {
"put": {
"operationId": "updateVirtualDesktopSchedule",
"tags": [
"Virtual Desktops"
],
"summary": "Update virtual desktop schedule",
"description": "Update the start/stop schedule for a DCV virtual desktop session",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid",
"schedule"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the virtual desktop session",
"example": "12345678-1234-1234-1234-123456789012"
},
"schedule": {
"type": "string",
"description": "JSON string containing weekly schedule with start/stop times in minutes (0-1440)",
"example": "{\"monday\":{\"start\":480,\"stop\":1020},\"tuesday\":{\"start\":480,\"stop\":1020},\"wednesday\":{\"start\":480,\"stop\":1020},\"thursday\":{\"start\":480,\"stop\":1020},\"friday\":{\"start\":480,\"stop\":1020},\"saturday\":{\"start\":0,\"stop\":0},\"sunday\":{\"start\":0,\"stop\":0}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Schedule updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your virtual desktop schedule has been updated"
}
}
}
}
}
},
"400": {
"description": "Invalid parameters or schedule format",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Unauthorized or session not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to find this session"
}
}
}
}
}
},
"500": {
"description": "Database error during update",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to update session schedule"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/list": {
"get": {
"operationId": "listVirtualDesktops",
"tags": [
"Virtual Desktops"
],
"summary": "List user's virtual desktop sessions",
"description": "Retrieves DCV desktop sessions for the authenticated user with optional filtering",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "is_active",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"description": "Filter sessions by active status",
"example": "true"
},
{
"name": "session_uuid",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by specific session UUID",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "state",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"stopping",
"terminated"
]
},
"description": "Filter by session state",
"example": "running"
}
],
"responses": {
"200": {
"description": "Successfully retrieved virtual desktop sessions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"session_uuid",
"session_name",
"session_state",
"instance_type",
"connection_string"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"session_name": {
"type": "string",
"example": "my-desktop"
},
"session_state": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"stopping",
"terminated"
],
"example": "running"
},
"instance_type": {
"type": "string",
"example": "m5.large"
},
"connection_string": {
"type": "string",
"format": "uri",
"example": "https://dcv.example.com/ip-10-0-1-100/?authToken=token123#session1"
},
"session_owner": {
"type": "string",
"example": "john.doe"
},
"os_family": {
"type": "string",
"enum": [
"linux",
"windows"
],
"example": "linux"
},
"instance_private_ip": {
"type": "string",
"format": "ipv4",
"nullable": true,
"example": "10.0.1.100"
},
"url": {
"type": "string",
"format": "uri",
"example": "https://dcv.example.com/ip-10-0-1-100/"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 400
},
"message": {
"type": "string",
"example": "Missing required parameter: is_active"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid user/token pair",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 401
},
"message": {
"type": "string",
"example": "Missing required header: X-SOCA-USER"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 500
},
"message": {
"type": "string",
"example": "Unable to retrieve SOCA Parameters"
}
}
}
}
}
}
}
}
},
"/api/dcv/authenticator": {
"post": {
"operationId": "authenticateDcvSession",
"tags": [
"Virtual Desktops"
],
"summary": "Authenticate DCV desktop session",
"description": "Validates DCV session authentication token and returns XML response for session access",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"sessionId",
"authenticationToken",
"clientAddress"
],
"properties": {
"sessionId": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "DCV session identifier",
"example": "dcv-session-123"
},
"authenticationToken": {
"type": "string",
"minLength": 1,
"maxLength": 10000,
"format": "base64",
"description": "Base64 encoded encrypted authentication token containing session details",
"example": "Z0FBQUFBQmhkX1pHVGtOcVRHVnNkR1Z5"
},
"clientAddress": {
"type": "string",
"format": "ipv4",
"description": "Client IP address requesting authentication",
"example": "192.168.1.100"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Authentication successful",
"content": {
"text/xml": {
"schema": {
"type": "string",
"pattern": "^[^<]+$"
},
"example": "john.doe"
}
}
},
"400": {
"description": "Missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 400
},
"message": {
"type": "string",
"example": "Missing required parameter: sessionId"
}
}
}
}
}
},
"401": {
"description": "Authentication failed - invalid credentials or session",
"content": {
"text/xml": {
"schema": {
"type": "string",
"pattern": "^$"
},
"example": ""
}
}
}
}
}
},
"/api/dcv/virtual_desktops/resize": {
"put": {
"operationId": "resizeVirtualDesktop",
"tags": [
"Virtual Desktops"
],
"summary": "Resize virtual desktop instance type",
"description": "Modify the instance type of a DCV desktop session. The session must be in stopped state.",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid",
"instance_type"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the virtual desktop session to resize",
"example": "12345678-1234-1234-1234-123456789abc"
},
"instance_type": {
"type": "string",
"description": "New EC2 instance type for the virtual desktop",
"example": "m5.large"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Virtual desktop successfully resized",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your virtual desktop has been updated"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing parameters or invalid instance type",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "CLIENT_MISSING_PARAMETER"
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing authentication headers",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "CLIENT_MISSING_HEADER"
},
"message": {
"type": "string",
"example": "Missing required header: X-SOCA-USER"
}
}
}
}
}
},
"403": {
"description": "Forbidden - session not owned by user or session not in stopped state",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "VIRTUAL_DESKTOP_MODIFY_ERROR"
},
"message": {
"type": "string",
"example": "This Virtual Desktop is not stopped. You can only modify a stopped desktop."
}
}
}
}
}
},
"500": {
"description": "Internal server error - AWS API or database error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "VIRTUAL_DESKTOP_MODIFY_ERROR"
},
"message": {
"type": "string",
"example": "Unable to modify this desktop because of AWS error"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/software_stacks": {
"get": {
"operationId": "getVirtualDesktopSoftwareStacks",
"tags": [
"Virtual Desktops"
],
"summary": "Get software stacks",
"description": "Retrieves software stacks for virtual desktops, optionally filtered by stack ID (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin.user"
},
"description": "SOCA username for authentication (must be admin)"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
},
{
"in": "query",
"name": "software_stack_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[0-9]+$",
"example": "1"
},
"description": "Specific software stack ID to retrieve (returns all if not specified)"
}
],
"responses": {
"200": {
"description": "Software stacks retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"stack_name": {
"type": "string",
"example": "Ubuntu Desktop 20.04"
},
"ami_id": {
"type": "string",
"example": "ami-12345678"
},
"base_os": {
"type": "string",
"example": "ubuntu2004"
},
"description": {
"type": "string",
"example": "Ubuntu 20.04 with desktop environment"
},
"root_size": {
"type": "integer",
"example": 50
},
"launch_tenancy": {
"type": "string",
"example": "default"
},
"virtual_desktop_profile_id": {
"type": "integer",
"example": 1
},
"project_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid software stack ID or no stacks found"
},
"403": {
"description": "Insufficient permissions or feature not enabled"
}
}
},
"post": {
"operationId": "createVirtualDesktopSoftwareStack",
"tags": [
"Virtual Desktops"
],
"summary": "Create software stack",
"description": "Creates a new software stack from an AMI for virtual desktop deployment (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin.user"
},
"description": "SOCA username for authentication (must be admin)"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"ami_id",
"stack_name",
"base_os",
"root_size",
"virtual_desktop_profile_id"
],
"properties": {
"ami_id": {
"type": "string",
"pattern": "f'^ami-[0-9a-f]{8,17}$'",
"description": "AMI ID to use for the software stack",
"example": "ami-12345678"
},
"stack_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Name for the software stack",
"example": "Ubuntu Desktop 20.04"
},
"base_os": {
"type": "string",
"minLength": 1,
"description": "Base operating system type",
"example": "ubuntu2004"
},
"root_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Root volume size in GB",
"example": "50"
},
"virtual_desktop_profile_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the virtual desktop profile to associate",
"example": "1"
},
"launch_tenancy": {
"type": "string",
"enum": [
"default",
"dedicated",
"host"
],
"description": "EC2 launch tenancy",
"example": "default"
},
"launch_host": {
"type": "string",
"pattern": "f'^h-[0-9a-f]{8,17}$'",
"description": "Dedicated host ID (only for host tenancy)",
"example": "h-1234567890abcdef0"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Description of the software stack (max 500 characters)",
"example": "Ubuntu 20.04 with desktop environment and development tools"
},
"thumbnail": {
"type": "string",
"format": "binary",
"description": "Thumbnail image for the software stack"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Software stack created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "ami-12345678 registered successfully in SOCA as Ubuntu Desktop 20.04"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters"
},
"401": {
"description": "Authentication failed"
},
"403": {
"description": "Insufficient permissions or feature not enabled"
},
"409": {
"description": "Stack name already exists"
},
"500": {
"description": "AWS API error or database error"
}
}
},
"delete": {
"operationId": "deleteVirtualDesktopSoftwareStack",
"tags": [
"Virtual Desktops"
],
"summary": "Deactivate software stack",
"description": "Deactivates an existing software stack for virtual desktops by marking it as inactive (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin.user"
},
"description": "SOCA username for authentication (must be admin)"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"software_stack_id"
],
"properties": {
"software_stack_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the software stack to deactivate",
"example": "1"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Software stack deactivated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Software Stack removed from SOCA"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters"
},
"401": {
"description": "Authentication failed"
},
"403": {
"description": "Insufficient permissions or feature not enabled"
},
"404": {
"description": "Software stack not found or already deactivated"
},
"500": {
"description": "Database error"
}
}
},
"put": {
"operationId": "updateVirtualDesktopSoftwareStack",
"tags": [
"Virtual Desktops"
],
"summary": "Update software stack",
"description": "Updates an existing software stack configuration for virtual desktop deployment (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin.user"
},
"description": "SOCA username for authentication (must be admin)"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"software_stack_id",
"ami_id",
"base_os",
"root_size",
"virtual_desktop_profile_id"
],
"properties": {
"software_stack_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the software stack to update",
"example": "1"
},
"ami_id": {
"type": "string",
"pattern": "f'^ami-[0-9a-f]{8,17}$'",
"description": "Updated AMI ID for the software stack",
"example": "ami-0abcdef1234567890"
},
"base_os": {
"type": "string",
"minLength": 1,
"description": "Updated base operating system",
"example": "ubuntu2004"
},
"root_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Updated root volume size in GB",
"example": "50"
},
"virtual_desktop_profile_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Updated virtual desktop profile ID",
"example": "1"
},
"launch_tenancy": {
"type": "string",
"enum": [
"default",
"dedicated",
"host"
],
"description": "Updated EC2 launch tenancy",
"example": "default"
},
"launch_host": {
"type": "string",
"pattern": "f'^h-[0-9a-f]{8,17}$'",
"description": "Updated dedicated host ID (only for host tenancy)",
"example": "h-1234567890abcdef0"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Updated description of the software stack (max 500 characters)",
"example": "Updated Ubuntu 20.04 with desktop environment and development tools"
},
"thumbnail": {
"type": "string",
"format": "binary",
"description": "Updated thumbnail image for the software stack"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Software stack updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "ami-0abcdef1234567890 updated successfully in SOCA"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters"
},
"401": {
"description": "Authentication failed"
},
"403": {
"description": "Insufficient permissions or feature not enabled"
},
"404": {
"description": "Software stack not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/dcv/virtual_desktops/list_all": {
"get": {
"operationId": "listAllVirtualDesktops",
"tags": [
"Virtual Desktops"
],
"summary": "List all virtual desktop sessions",
"description": "Retrieves detailed information about all active DCV virtual desktop sessions (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication (must be admin)",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"responses": {
"200": {
"description": "All virtual desktop sessions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"id",
"session_uuid",
"session_owner",
"session_name",
"session_state",
"instance_type",
"os_family"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"example": 1
},
"session_uuid": {
"type": "string",
"format": "uuid",
"example": "12345678-1234-1234-1234-123456789abc"
},
"session_owner": {
"type": "string",
"example": "john.doe"
},
"session_name": {
"type": "string",
"example": "MyDesktop01"
},
"session_state": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"stopping",
"terminated"
],
"example": "running"
},
"instance_type": {
"type": "string",
"example": "m5.large"
},
"instance_id": {
"type": "string",
"nullable": true,
"pattern": "^i-[a-f0-9]{8,17}$",
"example": "i-1234567890abcdef0"
},
"instance_private_ip": {
"type": "string",
"nullable": true,
"format": "ipv4",
"example": "10.0.1.100"
},
"os_family": {
"type": "string",
"enum": [
"linux",
"windows"
],
"example": "linux"
},
"software_stack": {
"type": "string",
"example": "Ubuntu Desktop (id: 1)"
},
"vdi_profile": {
"type": "string",
"example": "Standard Profile (id: 1)"
},
"created_on": {
"type": "string",
"format": "date-time",
"nullable": true
},
"is_active": {
"type": "boolean",
"example": true
}
}
},
"description": "Dictionary of session UUIDs mapped to session details"
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 401
},
"message": {
"type": "string",
"example": "Missing required header: X-SOCA-USER"
}
}
}
}
}
},
"403": {
"description": "Insufficient permissions or feature not enabled",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 403
},
"message": {
"type": "string",
"example": "Admin access required"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 500
},
"message": {
"type": "string",
"example": "Unable to retrieve SOCA Parameters"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/stop": {
"put": {
"operationId": "stopVirtualDesktop",
"tags": [
"Virtual Desktops"
],
"summary": "Stop virtual desktop",
"description": "Stop or hibernate a DCV virtual desktop session, automatically detecting hibernation capability",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the virtual desktop session to stop",
"example": "12345678-1234-1234-1234-123456789012"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Desktop stop/hibernate initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your desktop will be stopped soon."
}
}
}
}
}
},
"400": {
"description": "Missing required parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Session not found or already stopped",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Your desktop is already stopped."
}
}
}
}
}
},
"500": {
"description": "Failed to stop desktop",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to stop/hibernate instance"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/delete": {
"delete": {
"operationId": "deleteVirtualDesktop",
"tags": [
"Virtual Desktops"
],
"summary": "Delete virtual desktop session",
"description": "Terminates an active DCV virtual desktop session and cleans up associated resources",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the DCV session to delete",
"example": "12345678-1234-1234-1234-123456789abc"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Virtual desktop session deletion initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your Virtual Desktop is about to be terminated"
}
}
}
}
}
},
"400": {
"description": "Missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 400
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 401
},
"message": {
"type": "string",
"example": "Missing required header: X-SOCA-USER"
}
}
}
}
}
},
"403": {
"description": "Feature not enabled or insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 403
},
"message": {
"type": "string",
"example": "Virtual desktops feature is not enabled"
}
}
}
}
}
},
"404": {
"description": "Session not found or not active",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 404
},
"message": {
"type": "string",
"example": "This session does not exist or is not active"
}
}
}
}
}
},
"500": {
"description": "Internal server error during deletion",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 500
},
"message": {
"type": "string",
"example": "Unable to delete cloudformation stack"
}
}
}
}
}
}
}
}
},
"/api/dcv/virtual_desktops/create": {
"post": {
"operationId": "createVirtualDesktop",
"tags": [
"Virtual Desktops"
],
"summary": "Create new virtual desktop session",
"description": "Provisions a new EC2 instance with DCV for remote desktop access",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"instance_type",
"session_name",
"software_stack_id"
],
"properties": {
"instance_type": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9]+$",
"description": "EC2 instance type for the virtual desktop",
"example": "m5.large"
},
"disk_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "EBS root volume size in GB",
"example": "50"
},
"session_name": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"pattern": "^[a-zA-Z0-9]+$",
"description": "Name for the DCV session (alphanumeric only, max 32 chars)",
"example": "MyDesktop01"
},
"software_stack_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the software stack to use",
"example": "1"
},
"subnet_id": {
"type": "string",
"pattern": "^subnet-[a-f0-9]{8,17}$",
"description": "Subnet ID where to launch the EC2 instance",
"example": "subnet-12345678"
},
"project": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "Project to map the VDI desktop to",
"example": "myproject"
},
"hibernate": {
"type": "string",
"enum": [
"true",
"false"
],
"description": "Enable hibernation support",
"example": "false"
},
"tenancy": {
"type": "string",
"enum": [
"default",
"dedicated"
],
"description": "EC2 tenancy type",
"example": "default"
},
"session_type": {
"type": "string",
"enum": [
"default",
"console",
"virtual"
],
"description": "Type of DCV session",
"example": "default"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Virtual desktop session creation initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Session MyDesktop01 started successfully."
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 400
},
"message": {
"type": "string",
"example": "Missing required parameter: instance_type"
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 401
},
"message": {
"type": "string",
"example": "Invalid authentication credentials"
}
}
}
}
}
},
"403": {
"description": "Feature not enabled or insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 403
},
"message": {
"type": "string",
"example": "Virtual desktops feature is not enabled"
}
}
}
}
}
},
"500": {
"description": "Internal server error during session creation",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 500
},
"message": {
"type": "string",
"example": "Failed to create virtual desktop session"
}
}
}
}
}
}
}
}
},
"/api/ldap/user": {
"get": {
"operationId": "getLdapUser",
"tags": [
"User Management"
],
"summary": "Get user information",
"description": "Retrieve detailed information for a specific LDAP user by username or DN",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "user",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"example": "john.doe"
},
"description": "Username or DN of the user to retrieve"
}
],
"responses": {
"200": {
"description": "Successfully retrieved user information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "array",
"items": {
"type": "array",
"description": "LDAP entry data"
},
"example": [
[
"cn=john.doe,ou=people,dc=soca,dc=local",
{
"uid": [
"john.doe"
]
}
]
]
}
}
}
}
}
},
"203": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "User not found"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to connect to LDAP server"
}
}
}
}
}
}
}
},
"post": {
"operationId": "createLdapUser",
"tags": [
"User Management"
],
"summary": "Create new user",
"description": "Create a new LDAP user with home directory, SSH keys, and group membership",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user",
"password",
"sudoers",
"email"
],
"properties": {
"user": {
"type": "string",
"description": "Username for the new user (alphanumeric, _, -, . allowed, max 31 chars)",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "john.doe"
},
"password": {
"type": "string",
"description": "Password for the new user",
"minLength": 1,
"format": "password",
"example": "SecurePass123!"
},
"sudoers": {
"type": "integer",
"description": "Grant sudo permissions (1 = yes, 0 = no)",
"enum": [
0,
1
],
"example": 0
},
"email": {
"type": "string",
"description": "Email address for the user",
"format": "email",
"example": "john.doe@company.com"
},
"shell": {
"type": "string",
"description": "Login shell for the user",
"default": "/bin/bash",
"example": "/bin/bash"
},
"uid": {
"type": "integer",
"description": "Linux UID (0 = auto-assign)",
"minimum": 0,
"maximum": 65535,
"default": 0,
"example": 1001
},
"gid": {
"type": "integer",
"description": "Linux GID (0 = auto-assign)",
"minimum": 0,
"maximum": 65535,
"default": 0,
"example": 1001
}
}
}
}
}
},
"responses": {
"200": {
"description": "User created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "User created"
}
}
}
}
}
},
"203": {
"description": "User already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to create user, john.doe already exist"
}
}
}
}
}
},
"400": {
"description": "Invalid input parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to create user due to LDAP error"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteLdapUser",
"tags": [
"User Management"
],
"summary": "Delete user",
"description": "Delete a LDAP user and associated group. Home directory is backed up with timestamp suffix.",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "Username of the user to delete",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "john.doe"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Deleted user"
}
}
}
}
}
},
"203": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to delete user, john.doe does not seem to exist"
}
}
}
}
}
},
"400": {
"description": "Invalid request or self-deletion attempt",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You cannot request to delete your own account"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to delete user due to LDAP error"
}
}
}
}
}
}
}
}
},
"/api/ldap/users": {
"get": {
"operationId": "getAllLdapUsers",
"tags": [
"User Management"
],
"summary": "Retrieve all LDAP users",
"description": "Returns a list of all users from the configured LDAP directory (OpenLDAP or Active Directory)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"responses": {
"200": {
"description": "Successfully retrieved all LDAP users",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Dictionary of username to LDAP DN mappings",
"additionalProperties": {
"type": "string",
"description": "LDAP Distinguished Name"
},
"example": {
"john.doe": "cn=john.doe,ou=people,dc=soca,dc=local",
"jane.smith": "cn=jane.smith,ou=people,dc=soca,dc=local"
}
}
}
}
}
}
},
"203": {
"description": "Invalid username/token pair",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid authentication credentials"
}
}
}
}
}
},
"400": {
"description": "Malformed client input",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request parameters"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to connect to LDAP server"
}
}
}
}
}
}
}
}
},
"/api/ldap/sudo": {
"get": {
"operationId": "checkUserSudoPermissions",
"tags": [
"User Management"
],
"summary": "Check user sudo permissions",
"description": "Verify if a specific user has sudo/administrator privileges in the LDAP directory",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "user",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"description": "Username to check sudo permissions for"
}
],
"responses": {
"200": {
"description": "Successfully checked sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "john.doe has SUDO permissions"
}
}
}
}
}
},
"203": {
"description": "User does not have sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "john.doe does not have SUDO permissions"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to check SUDO permissions"
}
}
}
}
}
}
}
},
"post": {
"operationId": "grantUserSudoPermissions",
"tags": [
"User Management"
],
"summary": "Grant sudo permissions",
"description": "Grant sudo/administrator privileges to a user and update their API key scope",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "Username to grant sudo permissions to",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successfully granted sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "john.doe has now SUDO permissions"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter or invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"500": {
"description": "Failed to grant sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to grant SUDO permission to john.doe"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "revokeUserSudoPermissions",
"tags": [
"User Management"
],
"summary": "Revoke sudo permissions",
"description": "Remove sudo/administrator privileges from a user and downgrade their API key scope",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "Username to revoke sudo permissions from",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successfully revoked sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "john.doe does not have admin permission anymore"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"500": {
"description": "Failed to revoke sudo permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to remove admin permission for john.doe"
}
}
}
}
}
}
}
}
},
"/api/ldap/groups": {
"get": {
"operationId": "getAllLdapGroups",
"tags": [
"Group Management"
],
"summary": "Retrieve all LDAP groups",
"description": "Returns a list of all groups from the configured LDAP directory with their members",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"responses": {
"200": {
"description": "Successfully retrieved all LDAP groups",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Dictionary of group names to group information",
"additionalProperties": {
"type": "object",
"properties": {
"group_dn": {
"type": "string",
"description": "LDAP Distinguished Name of the group",
"example": "cn=developers,ou=group,dc=soca,dc=local"
},
"members": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of group members",
"example": [
"john.doe",
"jane.smith"
]
}
}
},
"example": {
"developers": {
"group_dn": "cn=developers,ou=group,dc=soca,dc=local",
"members": [
"john.doe",
"jane.smith"
]
},
"admins": {
"group_dn": "cn=admins,ou=group,dc=soca,dc=local",
"members": [
"admin"
]
}
}
}
}
}
}
}
},
"400": {
"description": "Malformed client input",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Bad request parameters"
}
}
}
}
}
},
"500": {
"description": "Unable to connect to LDAP server",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to list all groups"
}
}
}
}
}
}
}
}
},
"/api/ldap/group": {
"get": {
"operationId": "getLdapGroup",
"tags": [
"Group Management"
],
"summary": "Get group information",
"description": "Retrieve detailed information for a specific LDAP group including members",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "group",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "developers"
},
"description": "Name of the group to retrieve"
}
],
"responses": {
"200": {
"description": "Successfully retrieved group information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"properties": {
"group_dn": {
"type": "string",
"description": "LDAP Distinguished Name of the group",
"example": "cn=developers,ou=group,dc=soca,dc=local"
},
"members": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of group members",
"example": [
"john.doe",
"jane.smith"
]
}
}
}
}
}
}
}
},
"203": {
"description": "Group not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "LDAP group developers does not exist"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: group"
}
}
}
}
}
}
}
},
"post": {
"operationId": "createLdapGroup",
"tags": [
"Group Management"
],
"summary": "Create new group",
"description": "Create a new LDAP group with optional initial members",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"group"
],
"properties": {
"group": {
"type": "string",
"description": "Name of the group (alphanumeric, _, -, . allowed, max 31 chars)",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "developers"
},
"gid": {
"type": "integer",
"description": "Linux GID (auto-assigned if not provided)",
"minimum": 1000,
"maximum": 65535,
"example": 5001
},
"members": {
"type": "string",
"description": "Comma-separated list of usernames to add to the group",
"pattern": "^[a-zA-Z0-9._-]+(,[a-zA-Z0-9._-]+)*$",
"example": "john.doe,jane.smith"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Group created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Group created successfully"
}
}
}
}
}
},
"400": {
"description": "Invalid input or missing parameter",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: group"
}
}
}
}
}
},
"500": {
"description": "Backend error during group creation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to create group"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteLdapGroup",
"tags": [
"Group Management"
],
"summary": "Delete group",
"description": "Delete a LDAP group from the directory",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"group"
],
"properties": {
"group": {
"type": "string",
"description": "Name of the group to delete",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "developers"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Group deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Group deleted successfully"
}
}
}
}
}
},
"400": {
"description": "Missing parameter or self-deletion attempt",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "You cannot delete your own group"
}
}
}
}
}
},
"500": {
"description": "Failed to delete group",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to delete group"
}
}
}
}
}
}
}
},
"put": {
"operationId": "modifyLdapGroupMembership",
"tags": [
"Group Management"
],
"summary": "Modify group membership",
"description": "Add or remove a user from a LDAP group",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"group",
"user",
"action"
],
"properties": {
"group": {
"type": "string",
"description": "Name of the group to modify",
"minLength": 1,
"maxLength": 31,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$",
"example": "developers"
},
"user": {
"type": "string",
"description": "Username to add or remove from the group",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"action": {
"type": "string",
"description": "Action to perform",
"enum": [
"add",
"remove"
],
"example": "add"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Group membership modified successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Group updated successfully"
}
}
}
}
}
},
"400": {
"description": "Missing parameter or invalid action",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Action invalid is not supported"
}
}
}
}
}
},
"500": {
"description": "Failed to modify group membership",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to modify group"
}
}
}
}
}
}
}
}
},
"/api/ldap/ids": {
"get": {
"operationId": "getLdapIds",
"tags": [
"LDAP management"
],
"summary": "Get available UID/GID numbers",
"description": "Retrieve lists of used UID/GID numbers and get proposed available numbers for new user/group creation",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"responses": {
"200": {
"description": "Successfully retrieved UID/GID information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"properties": {
"proposed_uid": {
"type": "integer",
"description": "Suggested available UID for new user",
"minimum": 5001,
"maximum": 65533,
"example": 5001
},
"proposed_gid": {
"type": "integer",
"description": "Suggested available GID for new group",
"minimum": 5001,
"maximum": 65533,
"example": 5001
},
"uid_in_use": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1000,
"maximum": 65533
},
"description": "List of currently used UIDs",
"example": [
1000,
1001,
1002
]
},
"gid_in_use": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1000,
"maximum": 65533
},
"description": "List of currently used GIDs",
"example": [
1000,
1001,
1002
]
}
}
}
}
}
}
}
},
"500": {
"description": "Unable to contact LDAP server or lookup failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to lookup uidNumber"
}
}
}
}
}
}
}
}
},
"/api/ldap/authenticate": {
"post": {
"operationId": "authenticateLdapUser",
"tags": [
"LDAP management"
],
"summary": "Authenticate user credentials",
"description": "Validate LDAP user credentials and create home directory if needed",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user",
"password"
],
"properties": {
"user": {
"type": "string",
"description": "Username or DN to authenticate",
"minLength": 1,
"maxLength": 256,
"example": "john.doe"
},
"password": {
"type": "string",
"description": "Password for authentication",
"minLength": 1,
"format": "password",
"example": "userPassword123!"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Authentication successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Authentication successful"
}
}
}
}
}
},
"210": {
"description": "Invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid username or password"
}
}
}
}
}
},
"400": {
"description": "Missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: user"
}
}
}
}
}
},
"401": {
"description": "Unauthorized access",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized"
}
}
}
}
}
},
"500": {
"description": "Backend error during authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to connect to LDAP server"
}
}
}
}
}
}
}
}
},
"/api/user/reset_password": {
"post": {
"operationId": "resetActiveDirectoryPassword",
"tags": [
"User Management"
],
"summary": "Reset Active Directory user password",
"description": "Reset password for a user in AWS Directory Service (Active Directory) with complexity validation",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user",
"password"
],
"properties": {
"user": {
"type": "string",
"description": "Username of the user whose password will be reset",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"password": {
"type": "string",
"description": "New password (must meet AD complexity requirements - 8-64 chars with 3 of 4 character types)",
"minLength": 8,
"maxLength": 64,
"format": "password",
"example": "NewSecurePass123!"
},
"directory_id": {
"type": "string",
"description": "AWS Directory Service ID (uses default if not provided)",
"pattern": "f'^d-[0-9a-f]{10}$'",
"example": "d-1234567890"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Password successfully updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Password updated correctly"
}
}
}
}
}
},
"400": {
"description": "Invalid password or missing parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Password cannot contain username"
}
}
}
}
}
},
"500": {
"description": "Failed to update password",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "john.doe does not seem to exist in this directory"
}
}
}
}
}
}
}
}
},
"/api/projects": {
"get": {
"operationId": "getProjects",
"tags": [
"Projects"
],
"summary": "GET /api/projects",
"description": "GET operation for /api/projects",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "project_id",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[0-9]+$"
},
"required": false,
"description": "Specific project ID to retrieve",
"example": "1"
}
],
"responses": {
"200": {
"description": "Projects retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"example": {
"1": {
"id": 1,
"project_name": "default",
"description": "Default project"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid project_id parameter"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
}
}
},
"delete": {
"operationId": "deleteProject",
"tags": [
"Projects"
],
"summary": "DELETE /api/projects",
"description": "DELETE operation for /api/projects",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"project_id"
],
"properties": {
"project_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the project to delete",
"example": "2"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Project deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Project deleted successfully"
}
}
}
}
}
},
"400": {
"description": "Missing project_id or invalid ID"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required or default project cannot be deleted"
},
"404": {
"description": "Project not found"
},
"409": {
"description": "Project is in use by active software stacks"
}
}
}
},
"/api/user/resources_permissions": {
"get": {
"operationId": "getUserResourcePermissions",
"tags": [
"User Permissions"
],
"summary": "Get current user's resource permissions",
"description": "Retrieves resource permissions for the authenticated user (private API)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "user.name"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "virtual_desktops",
"in": "query",
"schema": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$"
},
"required": false,
"description": "Include virtual desktop permissions (\"all\" or comma-separated IDs)",
"example": "all"
},
{
"name": "target_nodes",
"in": "query",
"schema": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$"
},
"required": false,
"description": "Include target node permissions (\"all\" or comma-separated IDs)",
"example": "1,2,3"
},
{
"name": "application_profiles",
"in": "query",
"schema": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$"
},
"required": false,
"description": "Include application profiles (\"all\" or comma-separated IDs)",
"example": "all"
},
{
"name": "exclude_columns",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[a-zA-Z0-9_,]*$"
},
"required": false,
"description": "Comma-separated list of columns to exclude from response",
"example": "created_on,updated_on"
}
],
"responses": {
"200": {
"description": "User resource permissions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"properties": {
"user": {
"type": "string",
"example": "user.name"
},
"software_stacks": {
"type": "array",
"items": {
"type": "object"
},
"description": "Virtual desktop software stacks (if requested)"
},
"target_node_software_stacks": {
"type": "array",
"items": {
"type": "object"
},
"description": "Target node software stacks (if requested)"
},
"application_profiles": {
"type": "array",
"items": {
"type": "object"
},
"description": "Application profiles (if requested)"
}
}
}
}
}
}
}
},
"401": {
"description": "Missing authentication header"
},
"500": {
"description": "Database error"
}
}
},
"post": {
"operationId": "getUserResourcePermissionsAdmin",
"tags": [
"User Permissions"
],
"summary": "Get resource permissions for a specific user",
"description": "Retrieves resource permissions for a specified user (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication (must be admin)",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+$",
"minLength": 1,
"description": "Username to check permissions for",
"example": "target.user"
},
"virtual_desktops": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$",
"description": "Include virtual desktop permissions (\"all\" or comma-separated IDs)",
"example": "all"
},
"target_nodes": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$",
"description": "Include target node permissions (\"all\" or comma-separated IDs)",
"example": "1,2,3"
},
"application_profiles": {
"type": "string",
"pattern": "^(all|[0-9]+(,[0-9]+)*)?$",
"description": "Include application profiles (\"all\" or comma-separated IDs)",
"example": "all"
},
"exclude_columns": {
"type": "string",
"pattern": "^[a-zA-Z0-9_,]*$",
"description": "Comma-separated list of columns to exclude from response",
"example": "created_on,updated_on"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User resource permissions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"properties": {
"user": {
"type": "string",
"example": "target.user"
},
"software_stacks": {
"type": "array",
"items": {
"type": "object"
},
"description": "Virtual desktop software stacks (if requested)"
},
"target_node_software_stacks": {
"type": "array",
"items": {
"type": "object"
},
"description": "Target node software stacks (if requested)"
},
"application_profiles": {
"type": "array",
"items": {
"type": "object"
},
"description": "Application profiles (if requested)"
}
}
}
}
}
}
}
},
"400": {
"description": "Missing required parameters"
},
"403": {
"description": "Insufficient permissions"
},
"500": {
"description": "Database error"
}
}
}
},
"/api/user/api_key": {
"get": {
"operationId": "getUserApiKey",
"tags": [
"User API Keys"
],
"summary": "GET /api/user/api_key",
"description": "GET operation for /api/user/api_key",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-PASSWORD",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA password for the specified user",
"example": "mypassword"
},
{
"name": "user",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+$",
"minLength": 1
},
"required": true,
"description": "Username to retrieve API key for",
"example": "john.doe"
}
],
"responses": {
"200": {
"description": "API key retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"pattern": "f'^[a-f0-9]{32}$'",
"example": "a1b2c3d4e5f6789012345678"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter"
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "User not found"
}
}
},
"delete": {
"operationId": "deleteUserApiKey",
"tags": [
"User API Keys"
],
"summary": "DELETE /api/user/api_key",
"description": "DELETE operation for /api/user/api_key",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+$",
"minLength": 1,
"description": "Username to delete API key for",
"example": "john.doe"
}
}
}
}
}
},
"responses": {
"200": {
"description": "API key(s) deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Successfully deactivated"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter"
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "No active API key found for user"
}
}
}
},
"/api/target_nodes/schedule": {
"put": {
"operationId": "updateTargetNodeSchedule",
"tags": [
"Target Nodes"
],
"summary": "Update Target Nodes schedule",
"description": "Update the start/stop schedule for a Target Node session",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123def456"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid",
"schedule"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the Target Node session",
"example": "12345678-1234-1234-1234-123456789012"
},
"schedule": {
"type": "string",
"description": "JSON string containing weekly schedule with start/stop times in minutes (0-1440)",
"pattern": "f'^\\{.*\\}$'",
"example": "f'{\"monday\":{\"start\":480,\"stop\":1020},\"tuesday\":{\"start\":480,\"stop\":1020},\"wednesday\":{\"start\":480,\"stop\":1020},\"thursday\":{\"start\":480,\"stop\":1020},\"friday\":{\"start\":480,\"stop\":1020},\"saturday\":{\"start\":0,\"stop\":0},\"sunday\":{\"start\":0,\"stop\":0}}'"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Schedule updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your Target Node schedule has been updated"
}
}
}
}
}
},
"400": {
"description": "Invalid parameters or schedule format",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Unauthorized or session not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to find this session"
}
}
}
}
}
},
"500": {
"description": "Database error during update",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to update session schedule"
}
}
}
}
}
}
}
}
},
"/api/target_nodes/session_state": {
"get": {
"operationId": "getTargetNodeSessionStates",
"tags": [
"Target Nodes"
],
"summary": "Retrieve the current state of target node sessions",
"description": "Returns the current state (pending, running, stopped, etc.) for one or more target node sessions",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "session_uuid",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(,[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})*$",
"minLength": 1
},
"required": true,
"description": "Comma-separated list of session UUIDs to check",
"example": "550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001"
}
],
"responses": {
"200": {
"description": "Session states retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Dictionary mapping session UUIDs to their current states",
"additionalProperties": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"terminated",
"error"
]
},
"example": {
"550e8400-e29b-41d4-a716-446655440000": "running",
"660e8400-e29b-41d4-a716-446655440001": "stopped"
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
}
}
}
},
"/api/target_nodes/list": {
"get": {
"operationId": "listTargetNodeSessions",
"tags": [
"Target Nodes"
],
"summary": "Retrieve target node sessions for the authenticated user",
"description": "Returns a list of target node sessions with detailed information including connection strings and instance details",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
},
{
"name": "is_active",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"required": true,
"description": "Filter by active status (true/false)",
"example": "true"
},
{
"name": "session_uuid",
"in": "query",
"schema": {
"type": "string",
"format": "uuid",
"pattern": "f'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'"
},
"required": false,
"description": "Filter by specific session UUID",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"terminated",
"error"
]
},
"required": false,
"description": "Filter by session state",
"example": "running"
}
],
"responses": {
"200": {
"description": "Target node sessions retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Dictionary of session UUIDs mapped to session details",
"additionalProperties": {
"type": "object",
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid"
},
"session_name": {
"type": "string"
},
"session_owner": {
"type": "string"
},
"session_state": {
"type": "string",
"enum": [
"pending",
"running",
"stopped",
"terminated",
"error"
]
},
"instance_type": {
"type": "string"
},
"connection_string": {
"type": "string"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/target_nodes/delete": {
"delete": {
"operationId": "deleteTargetNodeSession",
"tags": [
"Target Nodes"
],
"summary": "Delete an existing target node session",
"description": "Terminates and removes a target node session including associated AWS resources",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "UUID of the target node session to delete",
"example": "550e8400-e29b-41d4-a716-446655440000"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node session deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your Target Node is about to be terminated"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"404": {
"description": "Session not found or not active"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/target_nodes/stop": {
"put": {
"operationId": "stopTargetNode",
"tags": [
"Target Nodes"
],
"summary": "Stop a running target node session",
"description": "Stop or hibernate a running target node session by session UUID",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123def456"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the target node session to stop",
"example": "12345678-1234-1234-1234-123456789abc"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node stop initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your target node will be stopped soon."
}
}
}
}
}
},
"400": {
"description": "Missing required parameter or session already stopped",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"enum": [
"Missing required parameter: session_uuid",
"Your target node is already stopped."
],
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Missing authentication header",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing X-SOCA-USER header"
}
}
}
}
}
},
"404": {
"description": "Session not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to find this session. Please refresh your browser and try again."
}
}
}
}
}
},
"500": {
"description": "AWS API error or database error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"enum": [
"Unable to stop/hibernate instance due to AWS error",
"Unable to set session_state to stopped due to database error"
],
"example": "Unable to stop/hibernate instance due to AWS error"
}
}
}
}
}
}
}
}
},
"/api/target_nodes/create": {
"post": {
"operationId": "createTargetNodeSession",
"tags": [
"Target Nodes"
],
"summary": "Create a new target node session for CAE simulations",
"description": "Creates a new target node session with specified configuration including instance type, software stack, and networking parameters",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"instance_type",
"session_name",
"software_stack_id",
"project"
],
"properties": {
"instance_type": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9]+$",
"description": "AWS EC2 instance type for the target node",
"example": "m5.large"
},
"session_name": {
"type": "string",
"pattern": "^[a-zA-Z0-9-]{1,32}$",
"maxLength": 32,
"description": "Name for the target node session (max 32 chars, alphanumeric and hyphens only)",
"example": "my-simulation-session"
},
"software_stack_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the software stack to use",
"example": "123"
},
"project": {
"type": "string",
"minLength": 1,
"description": "Project name for the target node session",
"example": "default"
},
"disk_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Root disk size in GB",
"example": "100"
},
"subnet_id": {
"type": "string",
"pattern": "^subnet-[a-f0-9]{8,17}$",
"description": "AWS subnet ID (random private subnet used if not specified)",
"example": "subnet-12345678"
},
"tenancy": {
"type": "string",
"enum": [
"default",
"dedicated",
"host"
],
"description": "EC2 tenancy type",
"example": "default"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node session created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Session my-simulation-session started successfully."
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Forbidden - user quota exceeded or access denied"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/target_nodes/user_data": {
"get": {
"operationId": "getUserDataTemplates",
"tags": [
"Target Nodes",
"User Data"
],
"summary": "Get user data templates",
"description": "Retrieve user data templates for target nodes",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123token"
},
"description": "SOCA authentication token"
},
{
"in": "query",
"name": "template_id",
"required": false,
"schema": {
"type": "string",
"pattern": "^[0-9]+$",
"example": "1"
},
"description": "Specific template ID to retrieve"
}
],
"responses": {
"200": {
"description": "User data templates retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"example": {
"1": {
"id": 1,
"template_name": "default",
"description": "Default template"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid template_id parameter"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
}
}
},
"post": {
"operationId": "createUserDataTemplate",
"tags": [
"Target Nodes",
"User Data"
],
"summary": "Create a new user data template",
"description": "Create a new user data template for target nodes",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123token"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"template_name",
"description",
"user_data"
],
"properties": {
"template_name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "Name for the user data template",
"example": "my-custom-template"
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Description of the template (max 500 characters)",
"example": "Custom user data template for CAE workloads"
},
"user_data": {
"type": "string",
"minLength": 1,
"maxLength": 16384,
"pattern": "^#!/bin/bash",
"description": "EC2 user data script (max 16KB)",
"example": "#!/bin/bash echo 'Hello World'"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User data template created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "User Data template has been created successfully"
}
}
}
}
}
},
"400": {
"description": "Missing required parameters or validation error"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"409": {
"description": "Template name already exists"
}
}
},
"delete": {
"operationId": "deleteUserDataTemplate",
"tags": [
"Target Nodes",
"User Data"
],
"summary": "Delete a user data template",
"description": "Delete a user data template for target nodes",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123token"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"template_id"
],
"properties": {
"template_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the template to delete",
"example": "2"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User data template deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "User Data Template deleted successfully"
}
}
}
}
}
},
"400": {
"description": "Missing template_id or invalid ID"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required or default template cannot be deleted"
},
"404": {
"description": "Template not found"
},
"409": {
"description": "Template is in use by active software stacks"
}
}
},
"put": {
"operationId": "updateUserDataTemplate",
"tags": [
"Target Nodes",
"User Data"
],
"summary": "Update an existing user data template",
"description": "Update an existing user data template for target nodes",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "admin"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123token"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"template_id",
"description",
"user_data"
],
"properties": {
"template_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the template to update",
"example": "2"
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Updated description (max 500 characters)",
"example": "Updated custom template description"
},
"user_data": {
"type": "string",
"minLength": 1,
"maxLength": 16384,
"pattern": "^#!/bin/bash ",
"description": "Updated EC2 user data script (max 16KB)",
"example": "#!/bin/bash echo 'Updated script'"
}
}
}
}
}
},
"responses": {
"200": {
"description": "User data template updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "User Data Template has been updated successfully"
}
}
}
}
}
},
"400": {
"description": "Missing required parameters or validation error"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"404": {
"description": "Template not found"
}
}
}
},
"/api/target_nodes/start": {
"put": {
"operationId": "startTargetNode",
"tags": [
"Target Nodes"
],
"summary": "Start a stopped target node session",
"description": "Restart a previously stopped target node session by session UUID",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123def456"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the target node session to start",
"example": "12345678-1234-1234-1234-123456789abc"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node start initiated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your target node is starting"
}
}
}
}
}
},
"400": {
"description": "Missing required parameter or invalid session state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"enum": [
"Missing required parameter: session_uuid",
"This target node is still being started. Please wait a little bit before restarting this session.",
"This target node seems to be already running."
],
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Missing authentication header",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing X-SOCA-USER header"
}
}
}
}
}
},
"404": {
"description": "Session not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to find this session. Please refresh your browser and try again."
}
}
}
}
}
},
"500": {
"description": "AWS API error or internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"enum": [
"Unable to create capacity reservation",
"Unable to start instance due to AWS error",
"Your current target node is not yet stopped. Please wait a little longer"
],
"example": "Unable to start instance due to AWS error"
}
}
}
}
}
}
}
}
},
"/api/target_nodes/profiles": {
"get": {
"operationId": "getTargetNodeProfiles",
"tags": [
"Target Nodes"
],
"summary": "Retrieve target node profiles",
"description": "Returns target node profile information including allowed instance types and subnet configurations",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
},
{
"name": "profile_id",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[0-9]+$"
},
"required": false,
"description": "Specific profile ID to retrieve (returns all if not specified)",
"example": "1"
}
],
"responses": {
"200": {
"description": "Target node profiles retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Dictionary of profile IDs mapped to profile details",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"profile_name": {
"type": "string"
},
"allowed_instance_types": {
"type": "string"
},
"max_root_size": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - invalid profile ID"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"500": {
"description": "Internal server error"
}
}
},
"post": {
"operationId": "createTargetNodeProfile",
"tags": [
"Target Nodes"
],
"summary": "Create a new target node profile",
"description": "Creates a new target node profile with specified instance types, subnets, and resource limits",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"profile_name",
"pattern_allowed_instance_types",
"allowed_subnet_ids",
"max_root_size"
],
"properties": {
"profile_name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"maxLength": 100,
"description": "Name for the new profile",
"example": "high-performance-profile"
},
"pattern_allowed_instance_types": {
"type": "string",
"pattern": "^[a-z0-9.*,\\s]+$",
"description": "Comma-separated list of allowed EC2 instance type patterns",
"example": "m5.*,c5.*"
},
"allowed_subnet_ids": {
"type": "string",
"pattern": "^subnet-[a-f0-9]{8,17}(,subnet-[a-f0-9]{8,17})*$",
"description": "Comma-separated list of allowed subnet IDs",
"example": "subnet-12345678,subnet-87654321"
},
"max_root_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Maximum root disk size in GB",
"example": "100"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Profile description (max 500 characters)",
"example": "Profile for high-performance computing workloads"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node profile created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "high-performance-profile registered successfully in SOCA"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"409": {
"description": "Conflict - profile name already exists"
},
"500": {
"description": "Internal server error"
}
}
},
"delete": {
"operationId": "deleteTargetNodeProfile",
"tags": [
"Target Nodes"
],
"summary": "Delete an existing target node profile",
"description": "Deactivates a target node profile if it's not being used by any software stacks",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"profile_id"
],
"properties": {
"profile_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the profile to delete",
"example": "2"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node profile deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Target Node Profile removed from SOCA"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Forbidden - cannot delete default profile or profile in use"
},
"404": {
"description": "Profile not found or already deactivated"
},
"500": {
"description": "Internal server error"
}
}
},
"put": {
"operationId": "updateTargetNodeProfile",
"tags": [
"Target Nodes"
],
"summary": "Update an existing target node profile",
"description": "Updates the configuration of an existing target node profile including instance types, subnets, and resource limits",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin.user"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "Authentication token for the SOCA user",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"profile_id",
"pattern_allowed_instance_types",
"allowed_subnet_ids",
"max_root_size"
],
"properties": {
"profile_id": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "ID of the profile to update",
"example": "2"
},
"pattern_allowed_instance_types": {
"type": "string",
"pattern": "^[a-z0-9.*,\\s]+$",
"description": "Comma-separated list of allowed EC2 instance type patterns",
"example": "m5.*,c5.*,r5.*"
},
"allowed_subnet_ids": {
"type": "string",
"pattern": "^subnet-[a-f0-9]{8,17}(,subnet-[a-f0-9]{8,17})*$",
"description": "Comma-separated list of allowed subnet IDs",
"example": "subnet-12345678,subnet-87654321"
},
"max_root_size": {
"type": "string",
"pattern": "^[0-9]+$",
"description": "Maximum root disk size in GB",
"example": "200"
},
"description": {
"type": "string",
"maxLength": 500,
"description": "Profile description (max 500 characters)",
"example": "Updated profile for high-performance computing workloads"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Target node profile updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Profile updated successfully"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing or invalid parameters"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"404": {
"description": "Profile not found"
},
"500": {
"description": "Internal server error"
}
}
}
},
"/api/target_nodes/resize": {
"put": {
"operationId": "resizeTargetNode",
"tags": [
"Virtual Desktops"
],
"summary": "Resize target node instance type",
"description": "Modify the instance type of a target node session. The session must be in stopped state.",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$",
"example": "john.doe"
},
"description": "SOCA username for authentication"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"example": "abc123def456"
},
"description": "SOCA authentication token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"session_uuid",
"instance_type"
],
"properties": {
"session_uuid": {
"type": "string",
"format": "uuid",
"description": "UUID of the virtual desktop session to resize",
"example": "12345678-1234-1234-1234-123456789abc"
},
"instance_type": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9]+$",
"description": "New EC2 instance type for the virtual desktop",
"example": "m5.large",
"enum": [
"t3.micro",
"t3.small",
"t3.medium",
"t3.large",
"m5.large",
"m5.xlarge",
"c5.large",
"c5.xlarge"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Virtual desktop successfully resized",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Your virtual desktop has been updated"
}
}
}
}
}
},
"400": {
"description": "Bad request - missing parameters or invalid instance type",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "CLIENT_MISSING_PARAMETER"
},
"message": {
"type": "string",
"example": "Missing required parameter: session_uuid"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing authentication headers",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "CLIENT_MISSING_HEADER"
},
"message": {
"type": "string",
"example": "Missing required header: X-SOCA-USER"
}
}
}
}
}
},
"403": {
"description": "Forbidden - session not owned by user or session not in stopped state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "VIRTUAL_DESKTOP_MODIFY_ERROR"
},
"message": {
"type": "string",
"example": "This Virtual Desktop is not stopped. You can only modify a stopped desktop."
}
}
}
}
}
},
"500": {
"description": "Internal server error - AWS API or database error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"error_code",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "string",
"example": "VIRTUAL_DESKTOP_MODIFY_ERROR"
},
"message": {
"type": "string",
"example": "Unable to modify this desktop because of AWS error"
}
}
}
}
}
}
}
}
},
"/api/system/files": {
"get": {
"operationId": "getFileContent",
"tags": [
"System Files"
],
"summary": "GET /api/system/files",
"description": "GET operation for /api/system/files",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "file",
"in": "query",
"schema": {
"type": "string",
"pattern": "^/[a-zA-Z0-9_./\\-]+$",
"minLength": 1
},
"required": true,
"description": "Full path to the file to read",
"example": "/home/user/config.txt"
}
],
"responses": {
"200": {
"description": "File content retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "File content here..."
}
}
}
}
}
},
"400": {
"description": "Missing file parameter or file not found"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Permission denied or restricted path"
}
}
},
"post": {
"operationId": "createOrUpdateFile",
"tags": [
"System Files"
],
"summary": "POST /api/system/files",
"description": "POST operation for /api/system/files",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"file_name",
"file_content"
],
"properties": {
"file_name": {
"type": "string",
"format": "base64",
"minLength": 1,
"description": "Base64 encoded file path",
"example": "L2hvbWUvdXNlci9jb25maWcudHh0"
},
"file_content": {
"type": "string",
"format": "base64",
"minLength": 1,
"description": "Base64 encoded file content",
"example": "SGVsbG8gV29ybGQ="
}
}
}
}
}
},
"responses": {
"200": {
"description": "File created/updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "File Updated."
}
}
}
}
}
},
"400": {
"description": "Missing parameters or invalid base64 encoding"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Permission denied to write file"
}
}
}
},
"/api/applications/list_applications": {
"get": {
"operationId": "listApplications",
"tags": [
"Applications"
],
"summary": "Get application profiles",
"description": "Retrieves all application profiles (admin access required)",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"in": "header",
"name": "X-SOCA-USER",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication (must be admin)",
"example": "admin.user"
},
{
"in": "header",
"name": "X-SOCA-TOKEN",
"required": true,
"schema": {
"type": "string",
"minLength": 10,
"maxLength": 1000
},
"description": "SOCA authentication token",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}
],
"responses": {
"200": {
"description": "Application profiles retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"profile_name": {
"type": "string",
"example": "ANSYS Fluent"
},
"created_by": {
"type": "string",
"example": "admin"
},
"profile_form": {
"type": "string",
"example": ""
},
"profile_job": {
"type": "string",
"example": "#!/bin/bash ..."
},
"profile_interpreter": {
"type": "string",
"example": "bash"
},
"profile_thumbnail": {
"type": "string",
"example": "data:image/png;base64,..."
},
"acl_allowed_users": {
"type": "string",
"example": "user1,user2"
},
"acl_restricted_users": {
"type": "string",
"example": "restricted_user"
},
"created_on": {
"type": "string",
"format": "date-time",
"example": "2024-01-15T10:30:00Z"
},
"deactivated_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": null
}
}
}
}
}
}
}
}
},
"403": {
"description": "Insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error_code": {
"type": "integer",
"example": 403
},
"message": {
"type": "string",
"example": "Admin access required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Error retrieving applications profile list, check logs for more details."
}
}
}
}
}
}
}
}
},
"/api/cost_management/budget": {
"get": {
"operationId": "getAwsBudgetInfo",
"tags": [
"Cost Management"
],
"summary": "Retrieve AWS budget information for a project",
"description": "Gets current spend, forecasted spend, total budget, and usage percentage for a specific project's AWS budget",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "project_name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "Name of the project",
"example": "my-research-project"
}
],
"responses": {
"200": {
"description": "Budget information retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"required": [
"budget_exist",
"current_spend",
"forecast_spend",
"total_budget",
"usage_pct"
],
"properties": {
"budget_exist": {
"type": "boolean",
"description": "Whether a budget exists for this project",
"example": true
},
"current_spend": {
"type": "number",
"minimum": 0,
"description": "Current spend amount in USD",
"example": 1250.75
},
"forecast_spend": {
"type": "number",
"minimum": 0,
"description": "Forecasted spend amount in USD",
"example": 1800.5
},
"total_budget": {
"type": "number",
"minimum": 0,
"description": "Total budget amount in USD",
"example": 5000.0
},
"usage_pct": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Usage percentage of total budget",
"example": 25.02
},
"forecast_pct": {
"type": "number",
"minimum": 0,
"description": "Forecasted usage percentage of total budget",
"example": 36.01
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: project_name"
}
}
}
}
}
},
"404": {
"description": "Project or budget not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Project my-research-project not found or deactivated"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to retrieve budget information, check log for more details"
}
}
}
}
}
}
}
}
},
"/api/cost_management/pricing": {
"get": {
"operationId": "calculateAwsPricing",
"tags": [
"Cost Management"
],
"summary": "Calculate AWS pricing for compute and storage resources",
"description": "Estimates the cost of running a job with specified compute and storage requirements",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "instance_type",
"in": "query",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9]+$"
},
"description": "EC2 instance type",
"example": "m5.large"
},
{
"name": "wall_time",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "f'^([0-9]{1,2}):([0-5][0-9]):([0-5][0-9])$'",
"default": "01:00:00"
},
"description": "Job duration in HH:MM:SS format",
"example": "02:30:00"
},
{
"name": "cpus",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"description": "Number of CPUs to allocate",
"example": 4
},
{
"name": "scratch_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000,
"default": 0
},
"description": "Scratch storage size in GB",
"example": 100
},
{
"name": "root_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 8,
"maximum": 1000,
"default": 40
},
"description": "Root disk size in GB",
"example": 50
},
{
"name": "fsx_capacity",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 100000,
"default": 0
},
"description": "FSx storage capacity in GB",
"example": 1200
},
{
"name": "fsx_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"SCRATCH_1",
"SCRATCH_2",
"PERSISTENT_1",
"PERSISTENT_2"
],
"default": "SCRATCH_2"
},
"description": "FSx storage type",
"example": "SCRATCH_2"
}
],
"responses": {
"200": {
"description": "Pricing calculation successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"required": [
"compute",
"estimated_total_cost",
"estimated_hourly_cost",
"estimated_storage_cost"
],
"properties": {
"compute": {
"type": "object",
"required": [
"on_demand_hourly_rate",
"reserved_hourly_rate",
"estimated_on_demand_cost",
"estimated_reserved_cost",
"nodes",
"walltime",
"instance_type"
],
"properties": {
"on_demand_hourly_rate": {
"type": "number",
"minimum": 0,
"example": 0.096
},
"reserved_hourly_rate": {
"type": "number",
"minimum": 0,
"example": 0.058
},
"estimated_on_demand_cost": {
"type": "number",
"minimum": 0,
"example": 0.192
},
"estimated_reserved_cost": {
"type": "number",
"minimum": 0,
"example": 0.116
},
"nodes": {
"type": "integer",
"minimum": 1,
"example": 1
},
"walltime": {
"type": "number",
"minimum": 0,
"example": 2.5
},
"instance_type": {
"type": "string",
"example": "m5.large"
},
"cpus": {
"type": "integer",
"nullable": true,
"example": 4
}
}
},
"estimated_total_cost": {
"type": "number",
"minimum": 0,
"example": 0.205
},
"estimated_hourly_cost": {
"type": "number",
"minimum": 0,
"example": 0.103
},
"estimated_storage_cost": {
"type": "number",
"minimum": 0,
"example": 0.013
},
"scratch_size": {
"type": "string",
"example": "0.007"
},
"root_size": {
"type": "string",
"example": "0.003"
},
"fsx_capacity": {
"type": "string",
"example": "0.003"
},
"storage_pct": {
"type": "number",
"minimum": 0,
"maximum": 100,
"example": 6.34
},
"compute_pct": {
"type": "string",
"example": "93.66"
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid parameters or wall_time format",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "wall_time must use HH:MM:SS format and only use valid numbers"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Authentication failed"
}
}
}
}
}
},
"404": {
"description": "Instance type pricing not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to retrieve price for m5.large"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to get compute price. Instance type may be incorrect or region name not tracked correctly?"
}
}
}
}
}
}
}
}
},
"/api/cost_management/budgets": {
"get": {
"operationId": "listAwsBudgets",
"tags": [
"Cost Management"
],
"summary": "List all available AWS budgets",
"description": "Retrieves a list of all AWS budgets available in the current account",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"responses": {
"200": {
"description": "List of available budgets retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": "List of budget names",
"example": [
"monthly-budget",
"quarterly-budget",
"project-alpha-budget"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Authentication failed"
}
}
}
}
}
},
"403": {
"description": "Forbidden - insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Admin access required"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Error retrieving budget list, check logs for more details."
}
}
}
}
}
}
}
}
},
"/api/containers/ecr/repository": {
"get": {
"operationId": "listEcrRepositoryImages",
"tags": [
"Elastic Container Registry (ECR)"
],
"summary": "Retrieve ECR repository images",
"description": "Lists Amazon ECR images from repositories tagged with the current SOCA cluster ID",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "repository",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+(,[a-zA-Z0-9._-]+)*$",
"maxLength": 1000
},
"description": "Comma-separated list of ECR repository names to inspect",
"example": "my-app,my-service"
}
],
"responses": {
"200": {
"description": "ECR images retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"required": [
"imageDigest",
"imageUri",
"pushedAt",
"imageSizeInMB"
],
"properties": {
"imageTag": {
"type": "string",
"nullable": true,
"example": "latest"
},
"imageDigest": {
"type": "string",
"pattern": "f'^sha256:[a-f0-9]{64}$'",
"example": "sha256:abc123def456"
},
"imageUri": {
"type": "string",
"format": "uri",
"example": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest"
},
"pushedAt": {
"type": "string",
"format": "date-time",
"example": "2024-01-15 10:30:00"
},
"imageSizeInMB": {
"type": "number",
"minimum": 0,
"example": 125.5
}
}
}
},
"example": {
"my-app": [
{
"imageTag": "latest",
"imageDigest": "sha256:abc123def456",
"imageUri": "123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
"pushedAt": "2024-01-15 10:30:00",
"imageSizeInMB": 125.5
}
]
}
}
}
}
}
}
},
"400": {
"description": "Bad request - invalid parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid repository name format"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Authentication failed"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to list ECR images"
}
}
}
}
}
}
}
}
},
"/api/containers/eks/list_clusters": {
"get": {
"operationId": "listEksClusters",
"tags": [
"Elastic Kubernetes Service (EKS)"
],
"summary": "List available EKS clusters",
"description": "Retrieves a list of EKS clusters that are tagged for visibility with the current SOCA cluster ID",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "cluster",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+(,[a-zA-Z0-9._-]+)*$",
"maxLength": 1000
},
"description": "Comma-separated list of specific cluster names to validate (optional)",
"example": "cluster1,cluster2"
}
],
"responses": {
"200": {
"description": "EKS clusters retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "List of available EKS cluster names",
"example": [
"my-soca-cluster-1",
"my-soca-cluster-2"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Authentication failed"
}
}
}
}
}
},
"403": {
"description": "Forbidden - insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Access denied to EKS resources"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to list EKS clusters"
}
}
}
}
}
}
}
}
},
"/api/containers/eks/job": {
"get": {
"operationId": "getEksJobDetails",
"tags": [
"Elastic Kubernetes Service (EKS)"
],
"summary": "Retrieve details of a specific EKS job",
"description": "Gets detailed information about an EKS job including status, configuration, and pod information",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "eks_cluster",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "Name of the EKS cluster",
"example": "my-soca-cluster"
},
{
"name": "job_name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
},
"description": "Name of the job to retrieve",
"example": "simulation-job-001"
},
{
"name": "namespace",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"default": "default"
},
"description": "Kubernetes namespace",
"example": "default"
}
],
"responses": {
"200": {
"description": "Job details retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"required": [
"job_name",
"status",
"namespace",
"cluster",
"owner"
],
"properties": {
"job_name": {
"type": "string",
"example": "simulation-job-001"
},
"status": {
"type": "string",
"enum": [
"Running",
"Succeeded",
"Failed",
"Unknown"
],
"example": "Running"
},
"namespace": {
"type": "string",
"example": "default"
},
"cluster": {
"type": "string",
"example": "my-soca-cluster"
},
"owner": {
"type": "string",
"example": "john.doe"
},
"created_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2024-01-15T10:30:00Z"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: job_name"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster"
}
}
}
}
}
},
"403": {
"description": "Forbidden - job does not belong to user",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "This job does not seem to belong to you"
}
}
}
}
}
},
"404": {
"description": "Job not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Job not found in namespace default"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to retrieve job details"
}
}
}
}
}
}
}
},
"post": {
"operationId": "submitEksJob",
"tags": [
"Elastic Kubernetes Service (EKS)"
],
"summary": "Submit a new EKS job",
"description": "Creates and submits a new job to the specified EKS cluster with the provided configuration",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"image_uri",
"eks_cluster",
"job_name"
],
"properties": {
"image_uri": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"pattern": "^[a-zA-Z0-9._/-]+:[a-zA-Z0-9._-]+$",
"description": "Container image URI to run",
"example": "nginx:latest"
},
"eks_cluster": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "Name of the EKS cluster",
"example": "my-soca-cluster"
},
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"description": "Unique name for the job",
"example": "simulation-job-001"
},
"cpu": {
"type": "string",
"pattern": "^[0-9]+(\\.[0-9]+)?$",
"default": "1",
"description": "CPU resource allocation (cores)",
"example": "2"
},
"memory": {
"type": "string",
"pattern": "^[0-9]+(\\.[0-9]+)?$",
"default": "1",
"description": "Memory allocation in GB",
"example": "4"
},
"instance_type": {
"type": "string",
"pattern": "^[a-z0-9]+\\.[a-z0-9]+$",
"description": "EC2 instance type for node selection",
"example": "m5.large"
},
"commandArray": {
"type": "string",
"format": "json",
"description": "JSON array of command to execute",
"example": "[\"echo\", \"hello\"]"
},
"argsArray": {
"type": "string",
"format": "json",
"description": "JSON array of arguments for the command",
"example": "[\"world\"]"
},
"namespace": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"default": "default",
"description": "Kubernetes namespace",
"example": "default"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Job submitted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Job submitted successfully"
}
}
}
}
}
},
"400": {
"description": "Bad request - invalid parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to parse command as JSON"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster"
}
}
}
}
}
},
"404": {
"description": "Namespace not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Namespace not found on your EKS cluster"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to submit EKS job"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteEksJob",
"tags": [
"Elastic Kubernetes Service (EKS)"
],
"summary": "Delete an existing EKS job",
"description": "Deletes an EKS job from the specified cluster and namespace. Only the job owner can delete their jobs.",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"eks_cluster",
"job_name"
],
"properties": {
"eks_cluster": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "Name of the EKS cluster where the job is running",
"example": "my-soca-cluster"
},
"job_name": {
"type": "string",
"minLength": 1,
"maxLength": 253,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"description": "Name of the job to delete",
"example": "simulation-job-001"
},
"namespace": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"default": "default",
"description": "Kubernetes namespace where the job is located",
"example": "default"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Job deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Job 'simulation-job-001' deleted successfully."
}
}
}
}
}
},
"400": {
"description": "Bad request - missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: job_name"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication or insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster"
}
}
}
}
}
},
"403": {
"description": "Forbidden - job does not belong to user",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "This job does not seem to belong to you"
}
}
}
}
}
},
"404": {
"description": "Job not found in the specified namespace",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Job simulation-job-001 not found in namespace default"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unable to delete job"
}
}
}
}
}
}
}
}
},
"/api/containers/eks/jobs": {
"get": {
"operationId": "listEksJobs",
"tags": [
"Elastic Kubernetes Service (EKS)"
],
"summary": "List all EKS jobs owned by the current user",
"description": "Retrieves a list of all EKS jobs owned by the authenticated user across tagged EKS clusters",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "SOCA username for authentication",
"example": "john.doe"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "SOCA authentication token",
"example": "abc123token456"
},
{
"name": "cluster",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._-]+$"
},
"description": "Name of the EKS cluster to query",
"example": "my-soca-cluster"
},
{
"name": "namespace",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 63,
"pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
"default": "default"
},
"description": "Kubernetes namespace to search in",
"example": "default"
}
],
"responses": {
"200": {
"description": "Jobs retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"metadata",
"status",
"pod_ips",
"images",
"eks_cluster"
],
"properties": {
"metadata": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "simulation-job-001"
},
"namespace": {
"type": "string",
"example": "default"
}
}
},
"status": {
"type": "object",
"properties": {
"active": {
"type": "integer",
"minimum": 0,
"example": 1
}
}
},
"pod_ips": {
"type": "array",
"items": {
"type": "string",
"format": "ipv4"
},
"example": [
"10.0.1.100"
]
},
"images": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"nginx:latest"
]
},
"eks_cluster": {
"type": "string",
"example": "my-soca-cluster"
}
}
},
"example": {
"job-uid-123": {
"metadata": {
"name": "simulation-job-001",
"namespace": "default"
},
"status": {
"active": 1
},
"pod_ips": [
"10.0.1.100"
],
"images": [
"nginx:latest"
],
"eks_cluster": "my-soca-cluster"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request - missing required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing required parameter: cluster"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid authentication",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Unauthorized: Verify if the IAM role is allowed to connect to cluster"
}
}
}
}
}
},
"404": {
"description": "Namespace not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Namespace not found on your EKS cluster"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Error listing jobs across clusters"
}
}
}
}
}
}
}
}
},
"/api/scheduler/queue": {
"post": {
"operationId": "createQueue",
"tags": [
"PBS Pro Scheduler"
],
"summary": "POST /api/scheduler/queue",
"description": "POST operation for /api/scheduler/queue",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"maxLength": 50,
"description": "Name of the queue to create",
"example": "my-queue"
},
"type": {
"type": "string",
"enum": [
"ondemand",
"alwayson"
],
"description": "Type of queue (ondemand or alwayson)",
"example": "ondemand"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Queue created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Queue my-queue created"
}
}
}
}
}
},
"400": {
"description": "Missing parameters or invalid queue type"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"409": {
"description": "Queue already exists"
},
"500": {
"description": "PBS scheduler error"
}
}
},
"delete": {
"operationId": "deleteQueue",
"tags": [
"PBS Pro Scheduler"
],
"summary": "DELETE /api/scheduler/queue",
"description": "DELETE operation for /api/scheduler/queue",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"maxLength": 50,
"description": "Name of the queue to delete",
"example": "my-queue"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Queue deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Queue my-queue deleted"
}
}
}
}
}
},
"400": {
"description": "Missing queue name parameter"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "Admin access required"
},
"404": {
"description": "Queue does not exist"
},
"500": {
"description": "PBS scheduler error"
}
}
}
},
"/api/scheduler/queues": {
"get": {
"operationId": "getQueues",
"tags": [
"PBS Pro Scheduler"
],
"summary": "GET /api/scheduler/queues",
"description": "GET operation for /api/scheduler/queues",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"responses": {
"200": {
"description": "List of queues retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$"
},
"example": [
"normal",
"high",
"low",
"gpu"
]
}
}
}
}
}
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "PBS scheduler error or backend failure"
}
}
}
},
"/api/scheduler/job": {
"get": {
"operationId": "getJob",
"tags": [
"PBS Pro Scheduler"
],
"summary": "GET /api/scheduler/job",
"description": "GET operation for /api/scheduler/job",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "job_id",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[0-9]+\\.[a-zA-Z0-9_.-]+$",
"minLength": 1
},
"required": true,
"description": "ID of the job to retrieve",
"example": "123.scheduler"
}
],
"responses": {
"200": {
"description": "Job information retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"properties": {
"Job_Name": {
"type": "string",
"example": "my_job"
},
"Job_Owner": {
"type": "string",
"example": "john.doe@cluster"
},
"job_state": {
"type": "string",
"enum": [
"Q",
"R",
"H",
"S",
"E",
"F"
],
"example": "R"
},
"queue": {
"type": "string",
"example": "normal"
}
}
}
}
}
}
}
},
"400": {
"description": "Missing job_id parameter"
},
"401": {
"description": "Authentication required"
},
"210": {
"description": "Job may have terminated"
}
}
},
"post": {
"operationId": "submitJob",
"tags": [
"PBS Pro Scheduler"
],
"summary": "POST /api/scheduler/job",
"description": "POST operation for /api/scheduler/job",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "string",
"format": "base64",
"minLength": 1,
"description": "Base64 encoded job submission script",
"example": "IyEvYmluL2Jhc2gKI1BCUyAtTiBteV9qb2IKZWNobyAiSGVsbG8gV29ybGQi"
},
"interpreter": {
"type": "string",
"enum": [
"qsub",
"bash"
],
"description": "Interpreter to use (qsub or bash)",
"example": "qsub"
},
"input_file_path": {
"type": "string",
"pattern": "^/[a-zA-Z0-9_./\\-]+/$",
"description": "Custom path for job output files",
"example": "/home/user/my_jobs/"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Job submitted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "123"
}
}
}
}
}
},
"400": {
"description": "Missing payload or invalid base64 encoding"
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "Job submission failed"
}
}
},
"delete": {
"operationId": "deleteJob",
"tags": [
"PBS Pro Scheduler"
],
"summary": "DELETE /api/scheduler/job",
"description": "DELETE operation for /api/scheduler/job",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"pattern": "^[0-9]+\\.[a-zA-Z0-9_.-]+$",
"minLength": 1,
"description": "ID of the job to delete",
"example": "123.scheduler"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Job deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Job deleted successfully"
}
}
}
}
}
},
"400": {
"description": "Missing job_id parameter"
},
"401": {
"description": "Authentication required"
},
"403": {
"description": "User is not the job owner"
},
"404": {
"description": "Job not found or already terminated"
},
"500": {
"description": "Job deletion failed"
}
}
}
},
"/api/scheduler/jobs": {
"get": {
"operationId": "getJobs",
"tags": [
"PBS Pro Scheduler"
],
"summary": "GET /api/scheduler/jobs",
"description": "GET operation for /api/scheduler/jobs",
"security": [
{
"socaAuth": [],
"socaToken": []
}
],
"parameters": [
{
"name": "X-SOCA-USER",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA username for authentication",
"example": "admin"
},
{
"name": "X-SOCA-TOKEN",
"in": "header",
"schema": {
"type": "string",
"minLength": 1
},
"required": true,
"description": "SOCA authentication token",
"example": "abc123token"
},
{
"name": "user",
"in": "query",
"schema": {
"type": "string",
"pattern": "^[a-zA-Z0-9._-]+$",
"minLength": 1
},
"required": false,
"description": "Filter jobs by specific user (returns all jobs if not specified)",
"example": "john.doe"
}
],
"responses": {
"200": {
"description": "Jobs retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "object",
"description": "Job information keyed by job ID",
"additionalProperties": {
"type": "object",
"properties": {
"Job_Name": {
"type": "string",
"example": "my_job"
},
"Job_Owner": {
"type": "string",
"example": "john.doe@cluster"
},
"job_state": {
"type": "string",
"enum": [
"Q",
"R",
"H",
"S",
"E",
"F"
],
"example": "R"
},
"queue": {
"type": "string",
"example": "normal"
}
}
},
"example": {
"123.scheduler": {
"Job_Name": "my_job",
"Job_Owner": "john.doe@cluster",
"job_state": "R",
"queue": "normal"
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication required"
},
"500": {
"description": "PBS scheduler error or JSON parsing failure"
}
}
}
}
},
"components": {
"securitySchemes": {
"socaAuth": {
"type": "apiKey",
"in": "header",
"name": "X-SOCA-USER",
"description": "SOCA username for authentication"
},
"socaToken": {
"type": "apiKey",
"in": "header",
"name": "X-SOCA-TOKEN",
"description": "SOCA authentication token"
}
}
},
"security": [
{
"socaAuth": [],
"socaToken": []
}
]
}