{ "openapi": "3.1.0", "info": { "title": "Engineering Development Hub (EDH) API", "description": "API specification for EDH (formerly Scale Out Computing on AWS - 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/engineering-development-hub/tree/main" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" } }, "paths": { "/api/user/tokens//renew": { "post": { "operationId": "renewUserToken", "tags": [ "Token" ], "summary": "Extend a token's expiration time", "description": "Renew (extend) the expiration of the specified token by the policy's default\nlifetime. Renewal is subject to the token being marked renewable, admin policy\nallowing renewals, and the max_renewals limit not being reached.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA authentication token" }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the token to renew" } ], "responses": { "200": { "description": "Token renewed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "renewal_count": { "type": "integer" }, "max_renewals": { "type": "integer", "nullable": true } } } } } } } }, "400": { "description": "Token is revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "403": { "description": "Token is not renewable or max renewals reached or renewal disabled by policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "404": { "description": "Token not found or does not belong to the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/admin/tokens/policy": { "get": { "operationId": "adminGetTokenPolicy", "tags": [ "Token (Admin)" ], "summary": "Get the current token policy", "description": "Returns the full admin-configured token policy. Requires admin (sudo) privileges.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin username" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin authentication token" } ], "responses": { "200": { "description": "Token policy retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "max_tokens_per_user": { "type": "integer" }, "max_lifetime_hours": { "type": "integer" }, "default_lifetime_hours": { "type": "integer" }, "max_renewals": { "type": "integer" }, "renewal_allowed": { "type": "boolean" }, "require_expiration": { "type": "boolean" }, "global_deny": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Not authorized (requires admin privileges)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } }, "put": { "operationId": "adminUpdateTokenPolicy", "tags": [ "Token (Admin)" ], "summary": "Update the token policy", "description": "Merge-updates the token policy. Only the fields provided in the request body\nare updated; unspecified fields retain their current values. Requires admin\n(sudo) privileges. Changes take effect immediately for new token operations.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin username" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_tokens_per_user": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of active tokens per user" }, "max_lifetime_hours": { "type": "integer", "minimum": 1, "maximum": 8760, "description": "Maximum token lifetime in hours (up to 1 year)" }, "default_lifetime_hours": { "type": "integer", "minimum": 1, "description": "Default token lifetime when not specified by user" }, "max_renewals": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Maximum number of renewals per token" }, "renewal_allowed": { "type": "boolean", "description": "Whether token renewal is allowed globally" }, "require_expiration": { "type": "boolean", "description": "Whether all tokens must have an expiration" }, "global_deny": { "type": "object", "description": "Paths blocked for all scoped tokens. Keys are path patterns (prefix with /api/, suffix with * for wildcard). Values are arrays of HTTP methods.", "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "*" ] } } } } } } } }, "responses": { "200": { "description": "Policy updated successfully (returns merged policy)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "max_tokens_per_user": { "type": "integer" }, "max_lifetime_hours": { "type": "integer" }, "default_lifetime_hours": { "type": "integer" }, "max_renewals": { "type": "integer" }, "renewal_allowed": { "type": "boolean" }, "require_expiration": { "type": "boolean" }, "global_deny": { "type": "object" } } } } } } } }, "400": { "description": "Validation error in policy values", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authorized (requires admin privileges)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/user/tokens/policy": { "get": { "operationId": "getUserTokenPolicy", "tags": [ "Token" ], "summary": "Get the current token policy", "description": "Returns the admin-configured token policy that governs token creation, lifetime, and renewal limits. Read-only for non-admin users.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA authentication token" } ], "responses": { "200": { "description": "Token policy retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "max_tokens_per_user": { "type": "integer", "description": "Maximum number of active tokens per user" }, "max_lifetime_hours": { "type": "integer", "description": "Maximum token lifetime in hours" }, "default_lifetime_hours": { "type": "integer", "description": "Default token lifetime when not specified" }, "max_renewals": { "type": "integer", "description": "Maximum number of times a token can be renewed" }, "renewal_allowed": { "type": "boolean", "description": "Whether token renewal is allowed globally" }, "require_expiration": { "type": "boolean", "description": "Whether tokens must have an expiration" }, "global_deny": { "type": "object", "description": "Paths that are denied for all scoped tokens", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/admin/audit": { "get": { "operationId": "adminGetAuditLog", "tags": [ "Token (Admin)" ], "summary": "Query the token API audit log", "description": "Returns paginated audit log entries for scoped token API usage. Supports\nfiltering by user, token_id, path, method, status, and time range.\nRequires admin (sudo) privileges.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin username" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin authentication token" }, { "name": "user", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by username" }, { "name": "token_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by token ID" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by API path (supports wildcard suffix, e.g. /api/user/*)" }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "description": "Filter by HTTP method" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "success", "denied", "error" ] }, "description": "Filter by response status category" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Start of time range (ISO 8601)" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "End of time range (ISO 8601)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 1000 }, "description": "Maximum number of entries to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Number of entries to skip (pagination)" } ], "responses": { "200": { "description": "Audit log entries retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching entries" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" }, "user": { "type": "string" }, "token_id": { "type": "integer", "nullable": true }, "token_name": { "type": "string", "nullable": true }, "token_type": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "status_code": { "type": "integer" }, "ip": { "type": "string" }, "user_agent": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer", "nullable": true }, "denied_reason": { "type": "string", "nullable": true } } } } } } } } } } }, "401": { "description": "Not authorized (requires admin privileges)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/admin/tokens": { "get": { "operationId": "adminListTokens", "tags": [ "Token (Admin)" ], "summary": "List all active tokens across users", "description": "Returns all non-revoked, non-expired user-type tokens. Optionally filter by\na specific user via query parameter. Requires admin (sudo) privileges.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin username" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin authentication token" }, { "name": "user", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter tokens by a specific username" } ], "responses": { "200": { "description": "Token list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "user": { "type": "string" }, "name": { "type": "string" }, "hint": { "type": "string" }, "permissions": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time" }, "renewable": { "type": "boolean" }, "renewal_count": { "type": "integer" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_ip": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } } } } } } } }, "401": { "description": "Not authorized (requires admin privileges)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/user/tokens": { "get": { "operationId": "listUserTokens", "tags": [ "Token" ], "summary": "List active API tokens for the authenticated user", "description": "Returns all non-revoked, non-expired scoped API tokens owned by the caller. Session tokens are excluded.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA authentication token" } ], "responses": { "200": { "description": "Token list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "hint": { "type": "string", "description": "Last 8 characters of the token" }, "permissions": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "renewable": { "type": "boolean" }, "renewal_count": { "type": "integer" }, "max_renewals": { "type": "integer", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_ip": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" } } } } } } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/admin/tokens//": { "delete": { "operationId": "adminRevokeToken", "tags": [ "Token (Admin)" ], "summary": "Force-revoke a specific user's token", "description": "Allows an admin to revoke any user's token regardless of ownership. The token will immediately stop authenticating.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin username" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Admin authentication token" }, { "name": "target_user", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Username who owns the token" }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the token to revoke" } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token revoked" } } } } } }, "400": { "description": "Token already revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "401": { "description": "Not authorized (requires admin privileges)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "404": { "description": "Token not found or does not belong to the specified user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/user/tokens/": { "delete": { "operationId": "revokeUserToken", "tags": [ "Token" ], "summary": "Revoke one of the caller's API tokens", "description": "Permanently revokes the specified token. The token will no longer authenticate API requests.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" }, "description": "SOCA authentication token" }, { "name": "token_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the token to revoke" } ], "responses": { "200": { "description": "Token revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Token revoked" } } } } } }, "400": { "description": "Token already revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "404": { "description": "Token not found or does not belong to the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } } } } }, "/api/login_nodes/list": { "get": { "operationId": "listLoginNodes", "tags": [ "Login Nodes" ], "summary": "List all running login node instances", "description": "Retrieve full EC2 instance details for all running login nodes in the SOCA cluster", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "SOCA username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "SOCA authentication token" } ], "responses": { "200": { "description": "Login node instances retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "description": "List of EC2 instance objects for running login nodes", "items": { "type": "object", "description": "EC2 instance description (AWS DescribeInstances format)" } } } } } } }, "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-EDH-USER", "required": true, "schema": { "type": "string", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-EDH-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-EDH-USER", "required": true, "schema": { "type": "string", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-EDH-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/session_sharing/connect": { "post": { "operationId": "createSessionSharingConnectNonce", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session_sharing/connect", "description": "POST operation for /api/dcv/session_sharing/connect", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_id" ], "properties": { "grant_id": { "type": "string", "description": "ID of the active grant to connect to" } } } } } }, "responses": { "201": { "description": "Nonce created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "nonce_url": { "type": "string", "description": "URL path to consume the nonce" } } } } } } } }, "400": { "description": "Missing grant_id" }, "403": { "description": "Not authorized for this grant" }, "404": { "description": "Grant not found or inactive" }, "500": { "description": "Serialization error" }, "503": { "description": "Cache (Valkey) not available" } } } }, "/api/dcv/session_sharing/connect/": { "get": { "operationId": "consumeSessionSharingConnectNonce", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/connect/", "description": "GET operation for /api/dcv/session_sharing/connect/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "nonce", "in": "path", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "Single-use nonce (30s TTL)" } ], "responses": { "302": { "description": "Redirect to DCV gateway with connection token" }, "403": { "description": "Nonce does not belong to the authenticated user" }, "410": { "description": "Nonce expired or already used" }, "502": { "description": "Failed to obtain connection token from broker" }, "503": { "description": "Cache or broker unavailable" } } } }, "/api/dcv/session_sharing/link": { "post": { "operationId": "createSessionSharingLink", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session_sharing/link", "description": "POST operation for /api/dcv/session_sharing/link", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_id" ], "properties": { "grant_id": { "type": "string", "description": "ID of the active grant to generate a link for" } } } } } }, "responses": { "200": { "description": "DCV link generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "dcv_url": { "type": "string", "description": "Full DCV gateway URL with embedded auth token" } } } } } } } }, "400": { "description": "Missing grant_id" }, "403": { "description": "Not authorized or link sharing not enabled" }, "404": { "description": "Grant not found or inactive" }, "502": { "description": "Failed to obtain connection token from broker" }, "503": { "description": "Broker unavailable" } } } }, "/api/dcv/virtual_desktops/connection_file": { "get": { "operationId": "getVirtualDesktopConnectionFile", "tags": [ "Virtual Desktops" ], "summary": "Fetch the .dcv connection file for a session", "description": "Returns the .dcv connection file (as text/plain attachment)\nfor the specified session. The caller must be the session owner\nor hold the admin token. Same payload as the WebUI route.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "session_uuid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Session UUID" }, { "name": "owner", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Session owner. Defaults to X-EDH-USER. Only the admin token\nmay pass an owner different from itself; other tokens that\nattempt this get a 403.\n" } ], "responses": { "200": { "description": ".dcv connection file (text/plain attachment)" }, "400": { "description": "Missing session_uuid" }, "403": { "description": "Non-admin caller requested another user's session" }, "404": { "description": "Session not found or not owned by user" } } } }, "/api/dcv/virtual_desktops/instance_types": { "get": { "operationId": "searchVdiInstanceTypes", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/virtual_desktops/instance_types", "description": "GET operation for /api/dcv/virtual_desktops/instance_types", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Substring to match against instance type names (prefix matches ranked first)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "required": false, "description": "Maximum number of results to return" }, { "name": "arch", "in": "query", "schema": { "type": "string", "enum": [ "x86_64", "arm64" ] }, "required": false, "description": "Filter results to instance types supporting this CPU architecture" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "vcpu": { "type": "integer" }, "mem_mib": { "type": "integer" }, "mem_gib": { "type": "integer" }, "hibernation_supported": { "type": "boolean", "nullable": true }, "gpu": { "type": "integer" }, "gpu_name": { "type": "string", "nullable": true }, "gpu_mem_gib": { "type": "integer", "nullable": true }, "gpu_frac": { "type": "string", "nullable": true }, "arch": { "type": "string" }, "clock_ghz": { "type": "number", "nullable": true }, "cpu_mfr": { "type": "string" }, "disk": { "type": "string" } } } } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin privileges required" }, "500": { "description": "Server error" } } } }, "/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-EDH-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-EDH-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-EDH-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/session_sharing/profiles": { "get": { "operationId": "listSessionSharingProfiles", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/profiles", "description": "GET operation for /api/dcv/session_sharing/profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "all", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "When true, include disabled profiles (admin use)" } ], "responses": { "200": { "description": "List of session sharing profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object" } } } } } } }, "503": { "description": "Session sharing not enabled" } } }, "post": { "operationId": "createSessionSharingProfile", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session_sharing/profiles", "description": "POST operation for /api/dcv/session_sharing/profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_name", "permissions" ], "properties": { "profile_name": { "type": "string", "description": "Name of the sharing profile" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "List of permission strings for this profile" } } } } } }, "responses": { "200": { "description": "Profile created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Missing required fields" }, "503": { "description": "Session sharing not enabled" } } } }, "/api/dcv/session_sharing/profiles/": { "put": { "operationId": "updateSessionSharingProfile", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/session_sharing/profiles/", "description": "PUT operation for /api/dcv/session_sharing/profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the profile to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_name": { "type": "string", "description": "New name for the profile (not allowed on default profiles)" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Updated permissions list (not allowed on default profiles)" }, "enabled": { "type": "boolean", "description": "Enable or disable the profile" } } } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid request (e.g. editing default profile name/permissions)" }, "503": { "description": "Session sharing not enabled" } } }, "delete": { "operationId": "deleteSessionSharingProfile", "tags": [ "Virtual Desktops" ], "summary": "DELETE /api/dcv/session_sharing/profiles/", "description": "DELETE operation for /api/dcv/session_sharing/profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the profile to delete" } ], "responses": { "200": { "description": "Profile deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "409": { "description": "Profile is in use by active shares" }, "503": { "description": "Session sharing not enabled" } } } }, "/api/dcv/session_sharing/grants": { "get": { "operationId": "listSessionSharingGrants", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/grants", "description": "GET operation for /api/dcv/session_sharing/grants", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "all", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "When true, return all grants (admin only)" }, { "name": "session_id", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Filter grants by broker session ID" }, { "name": "guest_username", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Filter grants by guest username" }, { "name": "status", "in": "query", "schema": { "type": "string", "default": "ACTIVE" }, "required": false, "description": "Filter by grant status (ACTIVE, ALL, etc.)" } ], "responses": { "200": { "description": "List of grants", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Missing required filter parameter" }, "403": { "description": "Admin privileges required for all=true" }, "503": { "description": "Session sharing not enabled" } } }, "post": { "operationId": "createSessionSharingGrant", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session_sharing/grants", "description": "POST operation for /api/dcv/session_sharing/grants", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "guest_username", "profile_id", "expires_at" ], "properties": { "session_id": { "type": "string", "description": "Broker session ID of the session to share" }, "guest_username": { "type": "string", "description": "Username of the guest to grant access to" }, "profile_id": { "type": "string", "description": "ID of the permission profile to apply" }, "expires_at": { "type": "string", "description": "ISO 8601 expiration timestamp for the grant" }, "owner_username": { "type": "string", "description": "Session owner username (admin override only)" }, "unsupervised": { "type": "boolean", "description": "Whether to allow unsupervised access" } } } } } }, "responses": { "200": { "description": "Grant created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Missing required fields" }, "403": { "description": "Not authorized to share this session" }, "503": { "description": "Session sharing not enabled" } } } }, "/api/dcv/session_sharing/grants/": { "delete": { "operationId": "revokeSessionSharingGrant", "tags": [ "Virtual Desktops" ], "summary": "DELETE /api/dcv/session_sharing/grants/", "description": "DELETE operation for /api/dcv/session_sharing/grants/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "grant_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the grant to revoke" } ], "responses": { "200": { "description": "Grant revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "403": { "description": "Not authorized to revoke this grant" }, "404": { "description": "Grant not found" }, "503": { "description": "Session sharing not enabled" } } } }, "/api/dcv/session_sharing/shared_to_me": { "get": { "operationId": "listSessionsSharedToMe", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/shared_to_me", "description": "GET operation for /api/dcv/session_sharing/shared_to_me", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "List of active grants where current user is the guest", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object", "properties": { "grant_id": { "type": "string" }, "session_id": { "type": "string" }, "owner_username": { "type": "string" }, "session_uuid": { "type": "string" }, "base_os": { "type": "string" } } } } } } } } }, "503": { "description": "Session sharing not enabled" } } } }, "/api/dcv/session_sharing/users/search": { "get": { "operationId": "searchSessionSharingUsers", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/users/search", "description": "GET operation for /api/dcv/session_sharing/users/search", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2 }, "required": true, "description": "Search query substring (minimum 2 characters)" }, { "name": "exclude", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Username to exclude from results (defaults to current user)" } ], "responses": { "200": { "description": "Matching users (max 10)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "display_name": { "type": "string" } } } } } } } } }, "503": { "description": "User directory unavailable" } } } }, "/api/dcv/session_sharing/sessions": { "get": { "operationId": "listAdminSessionSharingSessions", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/sessions", "description": "GET operation for /api/dcv/session_sharing/sessions", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "List of running VDI sessions with sharing metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "broker_session_id": { "type": "string" }, "session_uuid": { "type": "string" }, "owner": { "type": "string" }, "state": { "type": "string" }, "base_os": { "type": "string" } } } }, "allow_unsupervised_access": { "type": "boolean" } } } } } } } }, "503": { "description": "Unable to list sessions" } } } }, "/api/dcv/session_sharing/settings": { "get": { "operationId": "getSessionSharingSettings", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/session_sharing/settings", "description": "GET operation for /api/dcv/session_sharing/settings", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Current session sharing settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "allowed_sharing_modes": { "type": "array", "items": { "type": "string" } }, "allow_unsupervised_access": { "type": "boolean" }, "guest_screenshot_enabled": { "type": "boolean" } } } } } } } } } }, "put": { "operationId": "updateSessionSharingSettings", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/session_sharing/settings", "description": "PUT operation for /api/dcv/session_sharing/settings", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_unsupervised_access": { "type": "boolean", "description": "Whether to allow unsupervised sharing access" }, "guest_screenshot_enabled": { "type": "boolean", "description": "Whether guests can see session screenshots" }, "allowed_sharing_modes": { "type": "array", "items": { "type": "string" }, "description": "List of allowed sharing modes (e.g. none, secure, link)" } } } } } }, "responses": { "200": { "description": "Settings updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid request (bad format or no recognized settings)" } } } }, "/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-EDH-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-EDH-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/pool_availability": { "get": { "operationId": "getVdiPoolAvailability", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/virtual_desktops/pool_availability", "description": "GET operation for /api/dcv/virtual_desktops/pool_availability", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "software_stack_id", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Scope results to a single software stack (omit for all enabled pools)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "ready_now": { "type": "integer", "description": "Available hot members for instant claim" }, "warming": { "type": "integer", "description": "Warm capacity starting up" }, "label": { "type": "string", "description": "Optional admin display tag" } } } } } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/virtual_desktops/instance_type_specs": { "get": { "operationId": "getVdiInstanceTypeSpecs", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/virtual_desktops/instance_type_specs", "description": "GET operation for /api/dcv/virtual_desktops/instance_type_specs", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "instance_types", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Comma-separated list of EC2 instance type names (e.g. m5.large,c5.xlarge)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "vcpu": { "type": "integer" }, "mem_mib": { "type": "integer", "nullable": true }, "mem_gib": { "type": "integer" }, "hibernation_supported": { "type": "boolean", "nullable": true }, "gpu": { "type": "integer" }, "gpu_name": { "type": "string" }, "gpu_mem_gib": { "type": "integer" }, "gpu_frac": { "type": "string" }, "arch": { "type": "string" }, "clock_ghz": { "type": "number" }, "cpu_mfr": { "type": "string" }, "disk": { "type": "string" } } } } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/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-EDH-USER", "required": true, "schema": { "type": "string", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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" }, "share_scope": { "type": "string", "enum": [ "none", "project", "cluster" ], "description": "Visibility scope for the software stack (default cluster)" } } } } } }, "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-EDH-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-EDH-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-EDH-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-EDH-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" }, "hardware_profile_id": { "type": "string", "description": "Hardware profile ID to bind to this 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/session_state": { "get": { "operationId": "getVirtualDesktopSessionStates", "tags": [ "Virtual Desktops" ], "summary": "Get session states for virtual desktops", "description": "Retrieves the current state of one or more DCV virtual desktop sessions", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "session_uuid", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}(,[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})*$" }, "description": "Comma-separated list of session UUIDs to check", "example": "12345678-1234-1234-1234-123456789abc,87654321-4321-4321-4321-cba987654321" } ], "responses": { "200": { "description": "Session states retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "additionalProperties": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "running", "stopped", "stopping", "terminated" ], "description": "Current session state" }, "ssm_ping": { "type": "string", "description": "SSM ping status (e.g. Online, Unknown)" }, "instance_id": { "type": "string", "nullable": true, "description": "EC2 instance ID (null if not yet provisioned)" }, "instance_private_ip": { "type": "string", "nullable": true, "description": "Instance private IP address" }, "instance_private_dns": { "type": "string", "nullable": true, "description": "Instance private DNS name" } } }, "description": "Dictionary mapping session UUIDs to their state objects", "example": { "12345678-1234-1234-1234-123456789abc": { "state": "running", "ssm_ping": "Online", "instance_id": "i-0abc123def456", "instance_private_ip": "10.0.1.100", "instance_private_dns": "ip-10-0-1-100.ec2.internal" } } } } } } } }, "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": "Invalid authentication credentials" } } } } } } } } }, "/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-EDH-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-EDH-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-EDH-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-EDH-USER", "required": true, "schema": { "type": "string", "example": "john.doe" }, "description": "SOCA username for authentication" }, { "in": "header", "name": "X-EDH-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-EDH-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-EDH-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-EDH-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/events/stream": { "get": { "operationId": "getDcvEventStreamGrid", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/events/stream", "description": "GET operation for /api/dcv/events/stream", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string" }, "required": false, "description": "Resume cursor for EventSource reconnect (ULID string)" }, { "name": "last_id", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Alternative resume cursor (used when Last-Event-ID header is not available)" } ], "responses": { "200": { "description": "SSE stream opened successfully", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream with session lifecycle events" } } } }, "400": { "description": "Missing required X-EDH-USER header" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/events/stream/": { "get": { "operationId": "getDcvEventStreamSession", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/events/stream/", "description": "GET operation for /api/dcv/events/stream/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "session_uuid", "in": "path", "schema": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" }, "required": true, "description": "UUID of the DCV session to stream events for" }, { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string" }, "required": false, "description": "Resume cursor for EventSource reconnect (ULID string)" }, { "name": "last_id", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Alternative resume cursor (used when Last-Event-ID header is not available)" } ], "responses": { "200": { "description": "SSE stream opened successfully with history replay followed by live updates", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream with session lifecycle events" } } } }, "400": { "description": "Missing required header or invalid session_uuid format" }, "401": { "description": "Authentication required" }, "404": { "description": "Session not found or not owned by the authenticated user" }, "500": { "description": "Server error" } } } }, "/api/dcv/virtual_desktops/screenshot": { "get": { "operationId": "getVirtualDesktopScreenshot", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/virtual_desktops/screenshot", "description": "GET operation for /api/dcv/virtual_desktops/screenshot", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "session_id", "in": "query", "schema": { "type": "string" }, "required": true, "description": "UUID of the DCV session to retrieve the screenshot for" } ], "responses": { "200": { "description": "Screenshot lookup result (success=true with URL, or success=false if unavailable)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "oneOf": [ { "type": "object", "description": "Pre-signed URL (when success is true)", "properties": { "url": { "type": "string", "format": "uri", "description": "Pre-signed S3 URL for the screenshot (expires in 5 minutes)" } } }, { "type": "string", "description": "Error message (when success is false, e.g. \"No screenshot available\")" } ] } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Not authorized to view the screenshot for this session" } } } }, "/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-EDH-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-EDH-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" }, "capacity_reservation_id": { "type": "string", "description": "Existing Capacity Reservation ID to assign", "example": "cr-abd123" }, "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" }, "nested_virtualization": { "type": "string", "enum": [ "true", "false" ], "description": "Enable nested virtualization support (requires feature flag)", "example": "false" }, "bootstrap_cache_bypass": { "type": "string", "enum": [ "true", "false" ], "description": "Bypass the bootstrap template cache for this session (debugging)", "example": "false" }, "on_behalf_of": { "type": "string", "description": "Admin-only - create session on behalf of another user", "example": "another.user" } } } } } }, "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/dcv/hardware_profiles": { "get": { "operationId": "listHardwareProfiles", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/hardware_profiles", "description": "GET operation for /api/dcv/hardware_profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "include_inactive", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Include inactive profiles (1, true, or yes to enable)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } }, "post": { "operationId": "createHardwareProfile", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/hardware_profiles", "description": "POST operation for /api/dcv/hardware_profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_name" ], "properties": { "profile_name": { "type": "string", "description": "Name for the new hardware profile" }, "description": { "type": "string", "description": "Optional description" }, "usb_profile_id": { "type": "string", "description": "Optional USB profile ID to link" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid input (e.g. usb_profile_id not an integer)" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/hardware_profiles/": { "get": { "operationId": "getHardwareProfile", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/hardware_profiles/", "description": "GET operation for /api/dcv/hardware_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "hp_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Hardware profile ID" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Hardware profile not found" }, "500": { "description": "Server error" } } }, "put": { "operationId": "updateHardwareProfile", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/hardware_profiles/", "description": "PUT operation for /api/dcv/hardware_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "hp_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Hardware profile ID" } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "profile_name": { "type": "string", "description": "Updated profile name" }, "description": { "type": "string", "description": "Updated description" }, "usb_profile_id": { "type": "string", "description": "USB profile ID to link (empty string clears the link)" }, "is_active": { "type": "string", "description": "Active state (1/true/yes or 0/false/no)" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid input (e.g. usb_profile_id not an integer)" }, "401": { "description": "Authentication required" }, "404": { "description": "Hardware profile not found" }, "500": { "description": "Server error" } } }, "delete": { "operationId": "deleteHardwareProfile", "tags": [ "Virtual Desktops" ], "summary": "DELETE /api/dcv/hardware_profiles/", "description": "DELETE operation for /api/dcv/hardware_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "hp_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "Hardware profile ID to deactivate" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Hardware profile not found" }, "500": { "description": "Server error" } } } }, "/api/dcv/hardware_profiles/bind": { "post": { "operationId": "bindHardwareProfile", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/hardware_profiles/bind", "description": "POST operation for /api/dcv/hardware_profiles/bind", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "target_type", "target_id" ], "properties": { "target_type": { "type": "string", "enum": [ "stack", "project" ], "description": "Type of target to bind (stack or project)" }, "target_id": { "type": "string", "description": "Integer ID of the target stack or project" }, "hardware_profile_id": { "type": "string", "description": "Hardware profile ID to bind (empty to clear)" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid input (bad target_type, target_id, or hardware_profile_id)" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/hardware_profiles/sub_profile_types": { "get": { "operationId": "listHardwareSubProfileTypes", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/hardware_profiles/sub_profile_types", "description": "GET operation for /api/dcv/hardware_profiles/sub_profile_types", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/hardware_profiles/bindings": { "get": { "operationId": "listHardwareProfileBindings", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/hardware_profiles/bindings", "description": "GET operation for /api/dcv/hardware_profiles/bindings", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/hardware_profiles/preview": { "get": { "operationId": "previewHardwareProfileAllowlist", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/hardware_profiles/preview", "description": "GET operation for /api/dcv/hardware_profiles/preview", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "software_stack_id", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Integer ID of the software stack to resolve" }, { "name": "project_id", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Optional integer ID of the project override" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid input (bad software_stack_id or project_id)" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/session-event": { "post": { "operationId": "postSessionEvent", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session-event", "description": "POST operation for /api/dcv/session-event", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-Attested-Instance", "in": "header", "schema": { "type": "string" }, "required": true, "description": "AWS-attested EC2 instance ID (set by relay Lambda from SQS SenderId) or control-plane principal name" }, { "name": "X-EDH-DcvRelay-HMAC", "in": "header", "schema": { "type": "string" }, "required": true, "description": "Base64-encoded HMAC-SHA-256 signature over the canonical request, keyed by the relay secret" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_type", "session_uuid", "instance_id", "event_timestamp", "nonce" ], "properties": { "event_type": { "type": "string", "enum": [ "placed", "placement_failed", "session-ready", "session-resumed", "session-failed", "session-heartbeat", "bootstrap-checkpoint", "bootstrap-status" ], "description": "The lifecycle event type" }, "session_uuid": { "type": "string", "format": "uuid", "description": "UUID of the DCV session" }, "instance_id": { "type": "string", "pattern": "^i-[0-9a-f]{8,17}$", "description": "EC2 instance ID (not required for control-plane callers)" }, "event_timestamp": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the event (must be within 5 min of server time)" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 128, "description": "Unique nonce for replay protection" }, "checkpoint": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$", "description": "Bootstrap checkpoint name (required for bootstrap-checkpoint events)" }, "sub_status": { "type": "string", "maxLength": 256, "description": "Free-form progress message (required for bootstrap-status events)" } } } } } }, "responses": { "204": { "description": "Event accepted and applied successfully" }, "401": { "description": "Authentication or validation failed (HMAC mismatch, missing fields, nonce replay, etc.)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "413": { "description": "Request body exceeds maximum size (16 KiB)" }, "500": { "description": "Internal error during event application" } } } }, "/api/dcv/session-event-rotation-test": { "post": { "operationId": "testSessionEventRotation", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/session-event-rotation-test", "description": "POST operation for /api/dcv/session-event-rotation-test", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-Attested-Instance", "in": "header", "schema": { "type": "string" }, "required": true, "description": "Sentinel instance identifier for rotation probe (e.g. i-rotation-probe)" }, { "name": "X-EDH-DcvRelay-HMAC", "in": "header", "schema": { "type": "string" }, "required": true, "description": "Base64-encoded HMAC-SHA-256 signature computed with the AWSPENDING relay key" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Arbitrary probe payload signed by the rotation Lambda" } } } }, "responses": { "204": { "description": "Rotation probe succeeded (AWSPENDING key verifies correctly)" }, "401": { "description": "HMAC verification failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "413": { "description": "Request body exceeds maximum size" }, "500": { "description": "Unable to fetch secret or create client" } } } }, "/api/dcv/virtual_desktops/software_stacks//pool": { "get": { "operationId": "getVdiPoolConfig", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/virtual_desktops/software_stacks//pool", "description": "GET operation for /api/dcv/virtual_desktops/software_stacks//pool", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "software_stack_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the VDI software stack" }, { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "description": "Pool configuration object or null if not configured" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin privileges required" }, "404": { "description": "Software stack not found" }, "500": { "description": "Server error" } } }, "put": { "operationId": "putVdiPoolConfig", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/virtual_desktops/software_stacks//pool", "description": "PUT operation for /api/dcv/virtual_desktops/software_stacks//pool", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "software_stack_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the VDI software stack" }, { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Desired pool configuration state", "properties": { "pool_state": { "type": "string", "description": "Desired pool state (e.g. Hibernated)" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "instance_type": { "type": "string" }, "enabled": { "type": "boolean" }, "warm_count": { "type": "integer" }, "label": { "type": "string" } } } } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "pool_config": { "type": "string", "description": "JSON-encoded pool configuration" } } } } } }, "responses": { "200": { "description": "Pool config saved and reconcile triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid pool config or unknown instance types" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin privileges required" }, "404": { "description": "Software stack not found" }, "500": { "description": "Server error" } } }, "post": { "operationId": "recycleVdiPool", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/virtual_desktops/software_stacks//pool", "description": "POST operation for /api/dcv/virtual_desktops/software_stacks//pool", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "software_stack_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "ID of the VDI software stack whose pool members to recycle" }, { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Recycle triggered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin privileges required" }, "404": { "description": "Software stack not found" }, "500": { "description": "Server error or unable to trigger recycle" } } } }, "/api/dcv/virtual_desktops/pool/refresh-specs": { "post": { "operationId": "refreshVdiPoolSpecs", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/virtual_desktops/pool/refresh-specs", "description": "POST operation for /api/dcv/virtual_desktops/pool/refresh-specs", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Spec refresh completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "description": "Summary of pools refreshed" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin privileges required" }, "500": { "description": "Server error or refresh failed" } } } }, "/api/dcv/virtual_desktops/profiles": { "get": { "operationId": "getVirtualDesktopProfiles", "tags": [ "Virtual Desktops" ], "summary": "Get virtual desktop profiles", "description": "Retrieves virtual desktop profiles, optionally filtered by profile ID (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-USER", "required": true, "schema": { "type": "string", "example": "admin.user" }, "description": "SOCA username for authentication (must be admin)" }, { "in": "header", "name": "X-EDH-TOKEN", "required": true, "schema": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "description": "SOCA authentication token" }, { "in": "query", "name": "profile_id", "required": false, "schema": { "type": "string", "example": "1" }, "description": "Specific profile ID to retrieve (returns all if not specified)" } ], "responses": { "200": { "description": "Virtual desktop profiles retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "oneOf": [ { "type": "string", "example": "No Virtual Desktop Profiles found" }, { "type": "object", "additionalProperties": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "profile_name": { "type": "string", "example": "Standard Profile" }, "description": { "type": "string", "example": "Standard virtual desktop profile" }, "allowed_subnet_ids": { "type": "string", "example": "subnet-12345,subnet-67890" }, "pattern_allowed_instance_types": { "type": "string", "example": "m5.*,t3.*" }, "max_root_size": { "type": "integer", "example": 50 }, "software_stack_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } } } } ] } } } } } }, "400": { "description": "Invalid profile ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "profile_id does not seems to be a valid integer" } } } } } }, "403": { "description": "Insufficient permissions or feature not enabled", "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" } } } } } } } }, "post": { "operationId": "createVirtualDesktopProfile", "tags": [ "Virtual Desktops" ], "summary": "Create virtual desktop profile", "description": "Creates a new virtual desktop profile with specified configuration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-USER", "required": true, "schema": { "type": "string", "example": "admin.user" }, "description": "SOCA username for authentication (must be admin)" }, { "in": "header", "name": "X-EDH-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": [ "profile_name", "pattern_allowed_instance_types", "allowed_subnet_ids", "max_root_size", "description" ], "properties": { "profile_name": { "type": "string", "description": "Name for the virtual desktop profile", "example": "Engineering Profile" }, "pattern_allowed_instance_types": { "type": "string", "description": "Comma-separated patterns for allowed EC2 instance types", "example": "m5.*,c5.*,r5.*" }, "allowed_subnet_ids": { "type": "string", "description": "Comma-separated list of allowed subnet IDs", "example": "subnet-12345678,subnet-87654321" }, "max_root_size": { "type": "string", "description": "Maximum root volume size in GB", "example": "100" }, "description": { "type": "string", "maxLength": 500, "description": "Profile description (max 500 characters)", "example": "Profile for engineering workloads with high compute requirements" } } } } } }, "responses": { "200": { "description": "Virtual desktop profile created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Engineering Profile registered successfully in SOCA" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: profile_name" } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Missing required header: X-EDH-USER" } } } } } }, "403": { "description": "Insufficient permissions or feature not enabled", "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" } } } } } }, "409": { "description": "Profile name already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Profile name Engineering Profile already exists" } } } } } }, "500": { "description": "Database or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to add VDI Profile to DB" } } } } } } } }, "delete": { "operationId": "deleteVirtualDesktopProfile", "tags": [ "Virtual Desktops" ], "summary": "Delete virtual desktop profile", "description": "Deactivates a virtual desktop profile by setting is_active to false (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-USER", "required": true, "schema": { "type": "string", "example": "admin.user" }, "description": "SOCA username for authentication (must be admin)" }, { "in": "header", "name": "X-EDH-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": [ "profile_id" ], "properties": { "profile_id": { "type": "string", "description": "ID of the profile to delete", "example": "1" } } } } } }, "responses": { "200": { "description": "Virtual desktop profile deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "VDI Profile removed from SOCA" } } } } } }, "400": { "description": "Missing or invalid profile ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: profile_id" } } } } } }, "403": { "description": "Insufficient permissions or feature not enabled", "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" } } } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "VDI Profile not found or already deactivated" } } } } } }, "500": { "description": "Database error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to deactivate software stack due to database error" } } } } } } } }, "put": { "operationId": "updateVirtualDesktopProfile", "tags": [ "Virtual Desktops" ], "summary": "Update virtual desktop profile", "description": "Updates an existing virtual desktop profile with new configuration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-USER", "required": true, "schema": { "type": "string", "example": "admin.user" }, "description": "SOCA username for authentication (must be admin)" }, { "in": "header", "name": "X-EDH-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": [ "profile_id", "pattern_allowed_instance_types", "allowed_subnet_ids", "max_root_size", "description" ], "properties": { "profile_id": { "type": "string", "description": "ID of the profile to update", "example": "1" }, "pattern_allowed_instance_types": { "type": "string", "description": "Comma-separated patterns for allowed EC2 instance types", "example": "m5.*,c5.*,r5.*" }, "allowed_subnet_ids": { "type": "string", "description": "Comma-separated list of allowed subnet IDs", "example": "subnet-12345678,subnet-87654321" }, "max_root_size": { "type": "string", "description": "Maximum root volume size in GB", "example": "100" }, "description": { "type": "string", "maxLength": 500, "description": "Profile description (max 500 characters)", "example": "Updated profile for engineering workloads" } } } } } }, "responses": { "200": { "description": "Virtual desktop profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Profile updated successfully" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required parameter: profile_id" } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing required header: X-EDH-USER" } } } } } }, "403": { "description": "Insufficient permissions or feature not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Admin access required" } } } } } }, "404": { "description": "Profile not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to find existing virtual desktop profile" } } } } } }, "500": { "description": "Database or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to edit VDI Profile to DB" } } } } } } } } }, "/api/dcv/usb_profiles": { "get": { "operationId": "listUsbProfiles", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/usb_profiles", "description": "GET operation for /api/dcv/usb_profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "include_inactive", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Include inactive profiles (1, true, or yes to enable)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } }, "post": { "operationId": "createUsbProfile", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/usb_profiles", "description": "POST operation for /api/dcv/usb_profiles", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_name" ], "properties": { "profile_name": { "type": "string", "description": "Name for the new USB profile" }, "description": { "type": "string", "description": "Optional description" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/usb_profiles/": { "get": { "operationId": "getUsbProfile", "tags": [ "Virtual Desktops" ], "summary": "GET /api/dcv/usb_profiles/", "description": "GET operation for /api/dcv/usb_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "USB profile ID" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "USB profile not found" }, "500": { "description": "Server error" } } }, "put": { "operationId": "updateUsbProfile", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/usb_profiles/", "description": "PUT operation for /api/dcv/usb_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "USB profile ID" } ], "requestBody": { "required": false, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "profile_name": { "type": "string", "description": "Updated profile name" }, "description": { "type": "string", "description": "Updated description" }, "is_active": { "type": "string", "description": "Active state (1/true/yes or 0/false/no)" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "USB profile not found" }, "500": { "description": "Server error" } } }, "delete": { "operationId": "deleteUsbProfile", "tags": [ "Virtual Desktops" ], "summary": "DELETE /api/dcv/usb_profiles/", "description": "DELETE operation for /api/dcv/usb_profiles/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "USB profile ID to deactivate" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "USB profile not found" }, "500": { "description": "Server error" } } } }, "/api/dcv/usb_profiles//entries": { "post": { "operationId": "createUsbProfileEntry", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/usb_profiles//entries", "description": "POST operation for /api/dcv/usb_profiles//entries", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "USB profile ID to add the entry to" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "filter_string": { "type": "string", "description": "Raw DCV USB filter string (paste-to-parse; alternative to discrete fields)" }, "device_label": { "type": "string", "description": "Human-readable device label" }, "base_class": { "type": "string", "description": "USB base class code" }, "sub_class": { "type": "string", "description": "USB sub-class code" }, "protocol": { "type": "string", "description": "USB protocol code" }, "vid": { "type": "string", "description": "Vendor ID" }, "pid": { "type": "string", "description": "Product ID" }, "support_autoshare": { "type": "string", "description": "Whether to auto-share this device" }, "skip_reset": { "type": "string", "description": "Whether to skip USB reset" }, "enabled": { "type": "string", "description": "Whether this entry is enabled" }, "admin_comment": { "type": "string", "description": "Optional admin comment" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid filter string or entry fields" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } }, "put": { "operationId": "batchUpdateUsbProfileEntries", "tags": [ "Virtual Desktops" ], "summary": "PUT /api/dcv/usb_profiles//entries", "description": "PUT operation for /api/dcv/usb_profiles//entries", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "profile_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "USB profile ID" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "entries_json" ], "properties": { "entries_json": { "type": "string", "description": "JSON array of entry objects (each optionally carrying an existing integer id)" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid JSON in entries_json" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/api/dcv/usb_profiles/entries/": { "delete": { "operationId": "deleteUsbProfileEntry", "tags": [ "Virtual Desktops" ], "summary": "DELETE /api/dcv/usb_profiles/entries/", "description": "DELETE operation for /api/dcv/usb_profiles/entries/", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "entry_id", "in": "path", "schema": { "type": "integer" }, "required": true, "description": "ID of the USB allowlist entry to delete" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Entry not found" }, "500": { "description": "Server error" } } } }, "/api/dcv/usb_profiles/parse": { "post": { "operationId": "parseUsbFilterString", "tags": [ "Virtual Desktops" ], "summary": "POST /api/dcv/usb_profiles/parse", "description": "POST operation for /api/dcv/usb_profiles/parse", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "filter_string" ], "properties": { "filter_string": { "type": "string", "description": "Raw DCV USB filter string to validate and normalize" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Invalid filter string" }, "401": { "description": "Authentication required" }, "500": { "description": "Server error" } } } }, "/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). Supports optional typeahead mode via the q parameter.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "example": "john" }, "description": "Typeahead filter (minimum 2 characters). When provided, returns a small filtered list with username and display_name instead of the full directory." }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "example": 50 }, "description": "Maximum number of results to return in typeahead mode. Clamped to 1-200." } ], "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. Supports optional typeahead mode via the q parameter.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "example": "dev" }, "description": "Typeahead filter (minimum 2 characters). When provided, returns a small filtered list of matching group names instead of the full directory." }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "example": 50 }, "description": "Maximum number of results to return in typeahead mode. Clamped to 1-200." } ], "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": "^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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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/admin/bootstrap_cache": { "get": { "operationId": "getBootstrapCacheStatus", "tags": [ "Admin" ], "summary": "GET /api/admin/bootstrap_cache", "description": "GET operation for /api/admin/bootstrap_cache", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Cache status summary including config flags and entry list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "ttl_minutes": { "type": "integer" }, "cleanup_retention_days": { "type": "integer" }, "bucket": { "type": "string" }, "prefix": { "type": "string" }, "entry_count": { "type": "integer" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "last_modified": { "type": "string", "format": "date-time" }, "size": { "type": "integer" } } } } } } } } } } }, "401": { "description": "Authentication required or not an admin" }, "500": { "description": "Failed to read bootstrap cache state" } } } }, "/api/admin/bootstrap_cache/refresh": { "post": { "operationId": "refreshBootstrapCache", "tags": [ "Admin" ], "summary": "POST /api/admin/bootstrap_cache/refresh", "description": "POST operation for /api/admin/bootstrap_cache/refresh", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Cache markers deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "markers_deleted": { "type": "integer" }, "bucket": { "type": "string" }, "prefix": { "type": "string" } } } } } } } }, "401": { "description": "Authentication required or not an admin" }, "500": { "description": "Cache refresh operation failed" } } } }, "/api/admin/config/tree": { "get": { "operationId": "getConfigTree", "tags": [ "Admin" ], "summary": "GET /api/admin/config/tree", "description": "GET operation for /api/admin/config/tree", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Nested tree structure of configuration parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Failed to build configuration tree" } } } }, "/api/admin/config/params": { "get": { "operationId": "getConfigParams", "tags": [ "Admin" ], "summary": "GET /api/admin/config/params", "description": "GET operation for /api/admin/config/params", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "prefix", "in": "query", "schema": { "type": "string", "default": "/" }, "required": false, "description": "Parameter path prefix to list under (e.g. /configuration/...)" }, { "name": "direct", "in": "query", "schema": { "type": "string", "enum": [ "true", "false", "1", "0", "yes", "no" ] }, "required": false, "description": "If true, only return direct children of the prefix" } ], "responses": { "200": { "description": "Flat list of parameters under the specified prefix", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Failed to list configuration parameters" } } } }, "/api/admin/config/param": { "get": { "operationId": "getConfigParamDetail", "tags": [ "Admin" ], "summary": "GET /api/admin/config/param", "description": "GET operation for /api/admin/config/param", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "key", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Full parameter key path (e.g. /configuration/...)" } ], "responses": { "200": { "description": "Parameter value and associated policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Missing required key parameter" }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Failed to retrieve parameter detail" } } } }, "/api/admin/config/search": { "get": { "operationId": "searchConfigParams", "tags": [ "Admin" ], "summary": "GET /api/admin/config/search", "description": "GET operation for /api/admin/config/search", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Search query string" }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "key", "value", "both" ], "default": "both" }, "required": false, "description": "Search scope - match against key, value, or both (hidden params are redacted)" } ], "responses": { "200": { "description": "List of matching configuration parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Missing required query parameter q" }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Search operation failed" } } } }, "/api/admin/config/history": { "get": { "operationId": "getConfigParamHistory", "tags": [ "Admin" ], "summary": "GET /api/admin/config/history", "description": "GET operation for /api/admin/config/history", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "key", "in": "query", "schema": { "type": "string" }, "required": true, "description": "Full parameter key path (e.g. /configuration/...)" } ], "responses": { "200": { "description": "Version history of the specified parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "Missing required key parameter" }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Failed to retrieve parameter history" } } } }, "/api/admin/config/batch": { "post": { "operationId": "batchSetConfigParams", "tags": [ "Admin" ], "summary": "POST /api/admin/config/batch", "description": "POST operation for /api/admin/config/batch", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "changes_json" ], "properties": { "changes_json": { "type": "string", "description": "JSON array of objects with key and value fields" } } } } } }, "responses": { "200": { "description": "Per-parameter status of the batch write operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "400": { "description": "changes_json is missing or not valid JSON" }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Batch write operation failed" } } } }, "/api/admin/config/activity": { "get": { "operationId": "getConfigActivity", "tags": [ "Admin" ], "summary": "GET /api/admin/config/activity", "description": "GET operation for /api/admin/config/activity", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7 }, "required": false, "description": "Number of days of history to retrieve" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 200 }, "required": false, "description": "Maximum number of activity entries to return" } ], "responses": { "200": { "description": "Recent configuration change activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object" } } } } } }, "401": { "description": "Authentication required or not an admin" }, "403": { "description": "CONFIG_EDITOR feature flag is disabled" }, "500": { "description": "Failed to retrieve activity feed" } } } }, "/api/scheduler/job": { "get": { "operationId": "getJob", "tags": [ "Scheduler" ], "summary": "GET /api/scheduler/job", "description": "GET operation for /api/scheduler/job", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA authentication token", "example": "abc123token" }, { "name": "scheduler_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_.-]+$", "minLength": 1 }, "required": false, "description": "ID of scheduler. Optional if only one scheduler is configured", "example": "openpbs-soca-default" }, { "name": "serialize", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "minLength": 1 }, "required": false, "description": "Choose whether to serialize output. Recommended to set to true", "example": "true" }, { "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": [ "Scheduler" ], "summary": "POST /api/scheduler/job", "description": "POST operation for /api/scheduler/job", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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", "interpreter" ], "properties": { "payload": { "type": "string", "format": "base64", "minLength": 1, "description": "Base64 encoded job submission script", "example": "IyEvYmluL2Jhc2gKI1BCUyAtTiBteV9qb2IKZWNobyAiSGVsbG8gV29ybGQi" }, "interpreter": { "type": "string", "minLength": 1, "description": "Interpreter to use (either valid scheduler identifier or system interpreter such as /bin/bash, /bin/csh, /bin/sh or /bin/zsh)", "example": "qsub" } } } } } }, "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": [ "Scheduler" ], "summary": "DELETE /api/scheduler/job", "description": "DELETE operation for /api/scheduler/job", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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_id": { "type": "string", "pattern": "^[a-zA-Z0-9_.-]+$", "minLength": 1, "description": "ID of the scheduler. Optional if only one scheduler is configured", "example": "openpbs-soca-default" } } } } } }, "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": [ "Scheduler" ], "summary": "GET /api/scheduler/jobs", "description": "GET operation for /api/scheduler/jobs", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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" }, { "name": "queue", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$", "minLength": 1 }, "required": false, "description": "Filter jobs by specific queue (returns all jobs if not specified)", "example": "normal" }, { "name": "scheduler_id", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$", "minLength": 1 }, "required": false, "description": "Filter jobs by specific scheduler_id (returns all jobs if not specified)", "example": "openpbs-soca-default" } ], "responses": { "200": { "description": "Jobs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "description": "Jobs list and list of schedulers that returned an error", "properties": { "jobs": { "type": "array", "items": { "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" } } } }, "scheduler_errors": { "type": "array", "items": { "type": "string" }, "description": "List of scheduler identifiers that failed to return jobs", "example": [] } } } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "SOCA scheduler error or JSON parsing failure" } } } }, "/api/user/run_command": { "post": { "operationId": "runRemoteCommand", "tags": [ "User" ], "summary": "Execute a command as the specified user", "description": "Executes a command on the system as the specified user (private API)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username to execute command as", "example": "user.name" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "command" ], "properties": { "command": { "type": "string", "minLength": 1, "description": "Command to execute", "example": "ls -la /home" } } } } } }, "responses": { "200": { "description": "Command executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Command output", "example": "total 4 drwxr-xr-x 3 root root 4096 Jan 1 12:00 user.name" } } } } } }, "400": { "description": "Missing required parameter or header" }, "500": { "description": "Command execution failed" } } } }, "/api/user/preferences": { "get": { "operationId": "getUserPreferences", "tags": [ "User" ], "summary": "GET /api/user/preferences", "description": "GET operation for /api/user/preferences", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "key", "in": "path", "schema": { "type": "string" }, "required": false, "description": "Specific preference key to retrieve. If omitted, all preferences are returned." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "description": "Resolved preference(s) with value and metadata" } } } } } }, "400": { "description": "No authenticated user" }, "404": { "description": "Unknown preference key" } } }, "put": { "operationId": "updateUserPreference", "tags": [ "User" ], "summary": "PUT /api/user/preferences", "description": "PUT operation for /api/user/preferences", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "key", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Preference key to set" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "description": "The value to set for the preference (type depends on the preference catalog definition)" } } } } } }, "responses": { "200": { "description": "Preference set successfully, returns the resolved preference with metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "description": "Resolved preference with value, metadata, and source" } } } } } }, "400": { "description": "No authenticated user, missing key in URL, missing value in body, or validation error" }, "401": { "description": "Authentication required" } } }, "delete": { "operationId": "deleteUserPreferences", "tags": [ "User" ], "summary": "DELETE /api/user/preferences", "description": "DELETE operation for /api/user/preferences", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" }, { "name": "key", "in": "path", "schema": { "type": "string" }, "required": false, "description": "Specific preference key to reset. If omitted, all preferences are cleared." } ], "responses": { "200": { "description": "Preference(s) reset successfully (values fall back to defaults)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "No authenticated user or unknown preference key" }, "401": { "description": "Authentication required" } } } }, "/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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "user.name" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication (must be admin)", "example": "admin.user" }, { "name": "X-EDH-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" ], "summary": "GET /api/user/api_key", "description": "GET operation for /api/user/api_key", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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": "^[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" ], "summary": "DELETE /api/user/api_key", "description": "DELETE operation for /api/user/api_key", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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-EDH-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-EDH-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": "Missing authentication header", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing X-EDH-USER header" } } } } } }, "403": { "description": "Schedule update disabled by administrator", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Your administrator has disabled target node schedule update" } } } } } }, "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": "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": "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" } } } }, "/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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-EDH-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": "^[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/software_stacks": { "get": { "operationId": "getSoftwareStacks", "tags": [ "Target Nodes" ], "summary": "Retrieve software stacks", "description": "Get a list of all available software stacks or a specific software stack by ID", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" }, { "in": "query", "name": "software_stack_id", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1" }, "description": "ID of specific software stack to retrieve" } ], "responses": { "200": { "description": "Successfully retrieved software stacks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "example": { "1": { "id": 1, "stack_name": "Ubuntu 20.04", "ami_id": "ami-12345678", "root_size": 20, "project_ids": [ 1, 2 ] } } } } } } } }, "400": { "description": "Invalid software_stack_id parameter" }, "401": { "description": "Missing authentication header" } } }, "post": { "operationId": "createSoftwareStack", "tags": [ "Target Nodes" ], "summary": "Create a new software stack", "description": "Register a new software stack with AMI and configuration details", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "ami_id", "stack_name", "root_size", "target_node_profile_id", "target_node_user_data_id" ], "properties": { "ami_id": { "type": "string", "pattern": "^ami-[0-9a-f]{8,17}$", "description": "AWS AMI ID", "example": "ami-12345678" }, "stack_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name for the software stack", "example": "Ubuntu 20.04 LTS" }, "root_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Root volume size in GB", "example": "20" }, "launch_tenancy": { "type": "string", "enum": [ "default", "dedicated", "host" ], "description": "EC2 tenancy type", "example": "default" }, "launch_host": { "type": "string", "pattern": "^h-[0-9a-f]{8,17}$", "description": "Dedicated host ID (required if tenancy is 'host')", "example": "h-12345678" }, "user_data_variables": { "type": "string", "pattern": "^[a-zA-Z0-9_]+=.*$", "description": "User data variables in key=value,key2=value2 format", "example": "env=prod,region=us-east-1" }, "target_node_profile_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node profile ID", "example": "1" }, "connection_string": { "type": "string", "maxLength": 1000, "description": "Connection instructions (HTML allowed)", "example": "

Connect via SSH

ssh user@hostname

" }, "target_node_user_data_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node user data ID", "example": "1" }, "description": { "type": "string", "maxLength": 500, "description": "Description of the software stack (max 500 characters)", "example": "Ubuntu 20.04 LTS with 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 20.04 LTS" } } } } } }, "400": { "description": "Invalid input parameters" }, "401": { "description": "Missing authentication header" }, "409": { "description": "Software stack name already exists" }, "500": { "description": "AWS API error or internal server error" } } }, "delete": { "operationId": "deleteSoftwareStack", "tags": [ "Target Nodes" ], "summary": "Delete software stacks", "description": "Delete a Target Node Software Stack", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-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": [ "software_stack_id" ], "properties": { "software_stack_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of software stack to delete", "example": "1" } } } } } }, "responses": { "200": { "description": "Successfully deleted software stack", "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 software_stack_id parameter" }, "401": { "description": "Missing authentication header" }, "404": { "description": "Software stack not found" }, "500": { "description": "Database error during deletion" } } }, "put": { "operationId": "updateSoftwareStack", "tags": [ "Target Nodes" ], "summary": "Modify an existing software stack", "description": "Modify an existing software stack with AMI and configuration details", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 1, "example": "abc123token" }, "description": "SOCA authentication token" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "software_stack_id", "ami_id", "root_size", "target_node_profile_id", "target_node_user_data_id", "connection_string" ], "properties": { "software_stack_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of software stack to update", "example": "1" }, "ami_id": { "type": "string", "pattern": "^ami-[0-9a-f]{8,17}$", "description": "AWS AMI ID", "example": "ami-12345678" }, "root_size": { "type": "string", "pattern": "^[0-9]+$", "description": "Root volume size in GB", "example": "20" }, "launch_tenancy": { "type": "string", "enum": [ "default", "dedicated", "host" ], "description": "EC2 tenancy type", "example": "default" }, "launch_host": { "type": "string", "pattern": "^h-[0-9a-f]{8,17}$", "description": "Dedicated host ID (required if tenancy is 'host')", "example": "h-12345678" }, "user_data_variables": { "type": "string", "pattern": "^[a-zA-Z0-9_]+=.*$", "description": "User data variables in key=value,key2=value2 format", "example": "env=prod,region=us-east-1" }, "target_node_profile_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node profile ID", "example": "1" }, "connection_string": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Connection instructions (HTML allowed)", "example": "

Connect via SSH

ssh user@hostname

" }, "target_node_user_data_id": { "type": "string", "pattern": "^[0-9]+$", "description": "Target node user data ID", "example": "1" }, "description": { "type": "string", "maxLength": 500, "description": "Description of the software stack (max 500 characters)", "example": "Ubuntu 20.04 LTS with development tools" }, "thumbnail": { "type": "string", "format": "binary", "description": "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-12345678 updated successfully in SOCA" } } } } } }, "400": { "description": "Invalid input parameters" }, "401": { "description": "Missing authentication header" }, "404": { "description": "Software stack not found" }, "500": { "description": "AWS API error or 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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-EDH-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-EDH-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-EDH-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-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "john.doe" }, { "name": "X-EDH-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" }, "nested_virtualization": { "type": "string", "enum": [ "true", "false" ], "description": "Enable nested virtualization on the instance (requires EnableNestedVirtualization feature flag)", "example": "false" } } } } } }, "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-EDH-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-EDH-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-EDH-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-EDH-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" }, "500": { "description": "Database error during creation" } } }, "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-EDH-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-EDH-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" }, "500": { "description": "Database error during deletion" } } }, "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-EDH-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-EDH-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" }, "500": { "description": "Database error during update" } } } }, "/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-EDH-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-EDH-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-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin.user" }, { "name": "X-EDH-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": [ "Target Nodes" ], "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-EDH-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-EDH-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 target node 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 target node (must be allowed by the associated software stack profile)", "example": "m5.large" } } } } } }, "responses": { "200": { "description": "Target node 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-EDH-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 target node is not stopped. You can only modify a stopped target node." } } } } } }, "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 target node 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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "SOCA username for authentication", "example": "admin" }, { "name": "X-EDH-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/ai_assistant/mcp_servers": { "get": { "operationId": "listAiAssistantMcpServers", "tags": [ "AI Assistant" ], "summary": "GET /api/ai_assistant/mcp_servers", "description": "GET operation for /api/ai_assistant/mcp_servers", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "List of configured MCP servers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Server display name" }, "endpoint": { "type": "string", "description": "Server endpoint URL" }, "headers": { "type": "object", "nullable": true, "description": "Optional HTTP headers for the server connection" } } } } } } } } } } } }, "/api/ai_assistant/converse/stream": { "post": { "operationId": "aiAssistantConverseStream", "tags": [ "AI Assistant" ], "summary": "POST /api/ai_assistant/converse/stream", "description": "POST operation for /api/ai_assistant/converse/stream", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" }, "system_prompt": { "type": "string", "nullable": true }, "max_tokens": { "type": "integer", "nullable": true }, "temperature": { "type": "number", "nullable": true }, "top_p": { "type": "number", "nullable": true }, "inference_profile_arn": { "type": "string", "nullable": true, "description": "Custom Bedrock inference profile ARN" }, "model_id": { "type": "string", "nullable": true, "description": "Bedrock model ID to use for inference" }, "messages": { "type": "array", "nullable": true, "description": "Conversation history for context", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } }, "agent_runtime_id": { "type": "string", "nullable": true, "description": "Bedrock Agent runtime ID for agent-mode invocation" }, "session_id": { "type": "string", "nullable": true, "description": "Session ID for agent-mode conversation continuity" }, "conversation_id": { "type": "string", "nullable": true, "description": "Conversation identifier used to derive the agent session ID when session_id is not provided" }, "mcp_server_names": { "type": "array", "nullable": true, "description": "List of MCP server names to enable tool use during streaming", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "SSE stream of text chunks", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Streaming failed" } } } }, "/api/ai_assistant/converse": { "post": { "operationId": "aiAssistantConverse", "tags": [ "AI Assistant" ], "summary": "POST /api/ai_assistant/converse", "description": "POST operation for /api/ai_assistant/converse", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "EDH authentication token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The user message to send to the AI assistant", "example": "Why is my HPC job failing with mount errors?" }, "system_prompt": { "type": "string", "nullable": true, "description": "Optional system instruction to guide the AI response" }, "max_tokens": { "type": "integer", "nullable": true, "description": "Maximum number of tokens in the response", "example": 4096 }, "temperature": { "type": "number", "format": "float", "nullable": true, "description": "Temperature (0.0 = deterministic, 1.0 = creative)", "example": 0.0 }, "top_p": { "type": "number", "format": "float", "nullable": true, "description": "Top-p nucleus sampling parameter" }, "knowledge_base_id": { "type": "string", "nullable": true, "description": "Bedrock Knowledge Base ID for RAG-based responses" }, "number_of_results": { "type": "integer", "default": 5, "description": "Number of KB chunks to retrieve (only used with knowledge_base_id)" }, "inference_profile_arn": { "type": "string", "nullable": true, "description": "Custom Bedrock inference profile ARN. Defaults to cluster-configured model." }, "model_id": { "type": "string", "nullable": true, "description": "Bedrock model ID to use for inference. Defaults to cluster-configured model." }, "messages": { "type": "array", "nullable": true, "description": "Conversation history to provide context for the AI assistant", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "AI assistant response generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "message": { "type": "string", "description": "The AI-generated response text" }, "usage": { "type": "object", "nullable": true, "properties": { "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "totalTokens": { "type": "integer" } } } } } } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "AI assistant invocation failed" } } } }, "/api/ai_assistant/usage": { "get": { "operationId": "getAiAssistantUsage", "tags": [ "AI Assistant" ], "summary": "GET /api/ai_assistant/usage", "description": "GET operation for /api/ai_assistant/usage", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-USER", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH username for authentication" }, { "name": "X-EDH-TOKEN", "in": "header", "schema": { "type": "string" }, "required": true, "description": "EDH authentication token" } ], "responses": { "200": { "description": "Current daily token usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } } } } }, "/api/applications/export": { "get": { "operationId": "exportApplicationProfile", "tags": [ "Applications" ], "summary": "Export application profile", "description": "Exports an application profile configuration for backup or migration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "in": "query", "name": "application_id", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "ID of the application profile to export", "example": "1" } ], "responses": { "200": { "description": "Application profile exported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "object", "properties": { "Instructions:": { "type": "string", "example": "https://awslabs.github.io/engineering-development-hub-documentation/documentation/web-interface/import-export-application-profiles" }, "profile_form": { "type": "string", "example": "
" }, "profile_job": { "type": "string", "example": "#!/bin/bash module load ansys fluent -g" }, "profile_interpreter": { "type": "string", "example": "bash" }, "profile_thumbnail": { "type": "string", "example": "data:image/png;base64,..." } } } } } } } }, "400": { "description": "Missing application_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "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 (includes application not found or invalid application_id)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Application does not exist" } } } } } } } } }, "/api/applications/application": { "post": { "operationId": "createApplicationProfile", "tags": [ "Applications" ], "summary": "Create application profile", "description": "Creates a new application profile with job submission form and script (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "profile_name", "submit_job_form", "submit_job_script", "submit_job_interpreter" ], "properties": { "profile_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name for the application profile", "example": "ANSYS Fluent" }, "submit_job_form": { "type": "string", "minLength": 1, "description": "HTML form for job submission parameters", "example": "
" }, "submit_job_script": { "type": "string", "minLength": 1, "description": "Job submission script template", "example": "#!/bin/bash module load ansys fluent -g" }, "submit_job_interpreter": { "type": "string", "description": "Script interpreter (scheduler name or system shell)", "example": "bash" }, "thumbnail_b64": { "type": "string", "format": "base64", "description": "Base64 encoded thumbnail image for the application", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==" } } } } } }, "responses": { "200": { "description": "Application profile created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "ANSYS Fluent created successfully" } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: profile_name" } } } } } }, "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 during creation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to add new application db entry" } } } } } } } }, "put": { "operationId": "updateApplicationProfile", "tags": [ "Applications" ], "summary": "Update application profile", "description": "Updates an existing application profile with new configuration (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "application_id" ], "properties": { "application_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the application profile to update", "example": "1" }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Updated name for the application profile", "example": "ANSYS Fluent 2024" }, "submit_job_form": { "type": "string", "description": "Updated HTML form for job submission", "example": "
" }, "submit_job_script": { "type": "string", "description": "Updated job submission script template", "example": "#!/bin/bash module load ansys/2024 fluent -g" }, "submit_job_interpreter": { "type": "string", "description": "Updated script interpreter", "example": "bash" }, "thumbnail_b64": { "type": "string", "format": "base64", "description": "Updated base64 encoded thumbnail image", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==" } } } } } }, "responses": { "200": { "description": "Application profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application updated successfully" } } } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "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 (application not found, invalid parameters, or database error)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to edit existing application db entry" } } } } } } } }, "delete": { "operationId": "deleteApplicationProfile", "tags": [ "Applications" ], "summary": "Delete application profile", "description": "Deletes an existing application profile from the database (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "application_id" ], "properties": { "application_id": { "type": "string", "pattern": "^[0-9]+$", "description": "ID of the application profile to delete", "example": "1" } } } } } }, "responses": { "200": { "description": "Application profile deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application deleted successfully" } } } } } }, "400": { "description": "Missing application_id parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Missing required parameter: application_id" } } } } } }, "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 during deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to delete application db entry" } } } } } } } } }, "/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-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" }, { "in": "query", "name": "application_id", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1" }, "description": "Specific application ID to retrieve (returns all if not specified)" } ], "responses": { "200": { "description": "Application profiles retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "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/applications/import": { "post": { "operationId": "importApplicationProfile", "tags": [ "Applications" ], "summary": "Import application profile", "description": "Imports an application profile from a JSON file (admin access required)", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "in": "header", "name": "X-EDH-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-EDH-TOKEN", "required": true, "schema": { "type": "string", "minLength": 10, "maxLength": 1000 }, "description": "SOCA authentication token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "app_profile", "profile_name" ], "properties": { "app_profile": { "type": "string", "format": "binary", "description": "JSON file containing application profile configuration" }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name to assign to the imported application profile", "example": "ANSYS Fluent" } } } } } }, "responses": { "200": { "description": "Application profile imported successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Application Imported successfully" } } } } } }, "400": { "description": "Invalid JSON file or missing parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error_code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "This does not seem to be a valid JSON" } } } } } }, "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 during import", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Unable to import file. See log for 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-EDH-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-EDH-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", "forecast_available", "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 }, "forecast_available": { "type": "boolean", "description": "Whether forecast data is available from AWS", "example": true }, "total_budget": { "type": "number", "minimum": 0, "description": "Total budget amount in USD", "example": 5000.0 }, "usage_pct": { "type": "number", "minimum": 0, "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-EDH-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-EDH-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": "vcpus", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Number of vCPUs 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": [ "ondemand", "reserved", "on_demand_hourly_rate", "reserved_hourly_rate", "estimated_on_demand_cost", "estimated_reserved_cost", "nodes", "walltime", "instance_type", "vcpus" ], "properties": { "ondemand": { "type": "number", "minimum": 0, "description": "Raw on-demand price per hour from AWS Pricing API", "example": 0.096 }, "reserved": { "type": "number", "minimum": 0, "description": "Raw reserved price per hour from AWS Pricing API", "example": 0.058 }, "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" }, "vcpus": { "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": { "oneOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "integer" } ], "description": "Storage cost percentage of total (float when non-zero, integer 0 when no storage cost)", "example": 6.34 }, "compute_pct": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Compute cost percentage of total (string when non-zero, integer 0 when no compute cost)", "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-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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-EDH-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" } } } } } } } }, "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-EDH-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-EDH-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-EDH-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-EDH-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/containers/batch/job": { "get": { "operationId": "getBatchJobDetails", "tags": [ "AWS Batch" ], "summary": "Retrieve details of a specific AWS Batch job", "description": "Gets detailed information about an AWS Batch job including status, configuration, and container details", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "job_id", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "AWS Batch job ID", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "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", "properties": { "job_id": { "type": "string" }, "job_name": { "type": "string" }, "job_queue": { "type": "string" }, "status": { "type": "string" }, "job_definition": { "type": "string" }, "created_at": { "type": "integer" }, "started_at": { "type": "integer" }, "stopped_at": { "type": "integer" }, "status_reason": { "type": "string" } } } } } } } }, "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_id" } } } } } }, "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" } } } } } }, "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": "submitBatchJob", "tags": [ "AWS Batch" ], "summary": "Submit a new AWS Batch job", "description": "Creates and submits a new job to AWS Batch with the provided configuration", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-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": [ "job_name", "job_definition", "job_queue" ], "properties": { "job_name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Name for the job", "example": "my-batch-job" }, "job_definition": { "type": "string", "minLength": 1, "description": "ARN of the job definition", "example": "arn:aws:batch:us-east-1:123456789012:job-definition/my-def:1" }, "job_queue": { "type": "string", "minLength": 1, "description": "ARN of the job queue", "example": "arn:aws:batch:us-east-1:123456789012:job-queue/my-queue" }, "job_dependencies": { "type": "string", "description": "Comma-separated list of job IDs this job depends on", "example": "job-id-1,job-id-2" }, "array_size": { "type": "string", "description": "Array size for array jobs (2-10000)", "example": "10" }, "overrideCommands": { "type": "string", "format": "json", "description": "JSON array of command to override the container. First element is typically the executable, followed by arguments.", "example": "[\"python\", \"train.py\", \"--epochs\", \"10\"]" }, "envVars": { "type": "string", "format": "json", "description": "JSON array of environment variable objects", "example": "[{\"name\": \"MY_ENV\", \"value\": \"Hello\"}]" }, "scheduling_priority": { "type": "string", "description": "Scheduling priority (0-9999) for prioritizing jobs in a queue", "example": "100" }, "job_attempts": { "type": "string", "description": "Number of times to retry the job (1-10)", "example": "3" }, "execution_timeout": { "type": "string", "description": "Execution timeout in seconds after which the job is terminated", "example": "3600" }, "vcpus": { "type": "string", "description": "Number of vCPUs reserved for the container (e.g., 0.25, 1, 2)", "example": "1" }, "memory": { "type": "string", "description": "Hard limit of memory in GB to present to the container", "example": "2" }, "consumableResources": { "type": "string", "format": "json", "description": "JSON array of custom consumable resource objects (max 5 total including VCPU and MEMORY)", "example": "[{\"type\": \"GPU\", \"value\": \"1\"}, {\"type\": \"FPGA\", \"value\": \"2\"}]" } } } } } }, "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 my-batch-job submitted successfully. Job ID: a1b2c3d4" } } } } } }, "400": { "description": "Bad request - missing or invalid 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" } } } } } }, "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 AWS Batch job" } } } } } } } }, "delete": { "operationId": "deleteBatchJob", "tags": [ "AWS Batch" ], "summary": "Terminate an existing AWS Batch job", "description": "Terminates an AWS Batch job. Only the job owner can terminate their jobs.", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-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": [ "job_id" ], "properties": { "job_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "AWS Batch job ID to terminate", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "reason": { "type": "string", "maxLength": 1000, "default": "Terminated by user", "description": "Reason for terminating the job", "example": "No longer needed" } } } } } }, "responses": { "200": { "description": "Job terminated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job a1b2c3d4 terminated 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_id" } } } } } }, "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" } } } } } }, "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 terminate job" } } } } } } } } }, "/api/containers/batch/job_definition": { "get": { "operationId": "listBatchJobDefinitions", "tags": [ "AWS Batch" ], "summary": "List AWS Batch job definitions visible to this EDH environment", "description": "Retrieves AWS Batch job definitions that are tagged with the EDH visibility tag for this cluster.\nIf a specific job definition name is provided, only that definition is returned (if it has the correct tag).\nOtherwise, all matching definitions are returned with pagination handled automatically.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "job_definition", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Name of a specific job definition to look up. If omitted, all visible job definitions are returned.", "example": "my-job-def" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ], "default": "ACTIVE" }, "description": "Filter job definitions by status", "example": "ACTIVE" } ], "responses": { "200": { "description": "Job definitions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "object", "properties": { "jobDefinitionName": { "type": "string", "example": "my-job-def" }, "jobDefinitionArn": { "type": "string", "example": "arn:aws:batch:us-east-1:123456789012:job-definition/my-job-def:1" }, "revision": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "ACTIVE" }, "type": { "type": "string", "example": "container" }, "containerProperties": { "type": "object" }, "tags": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } } }, "400": { "description": "Bad request - feature disabled or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Feature CONTAINERS_MANAGEMENT_BATCH is not enabled" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not authorized" } } } } } }, "403": { "description": "Forbidden - IAM permission error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "IAM permission error: the role does not have sufficient permissions to call batch:DescribeJobDefinitions." } } } } } }, "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 job definitions. See log for more details" } } } } } } } } }, "/api/containers/batch/jobs": { "get": { "operationId": "listBatchJobs", "tags": [ "AWS Batch" ], "summary": "List all AWS Batch jobs owned by the requesting user", "description": "Lists AWS Batch jobs across all visible job queues (tagged with edh:visibility: = true).\nOnly jobs with matching soca_JobOwner and soca_ClusterId tags are returned.\nOptionally filter by a specific job queue or job status.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "job_queue", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "ARN or name of a specific job queue to list jobs from. If omitted, jobs from all visible queues are returned.", "example": "arn:aws:batch:us-east-1:123456789012:job-queue/my-queue" }, { "name": "job_status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SUBMITTED", "PENDING", "RUNNABLE", "STARTING", "RUNNING", "SUCCEEDED", "FAILED" ] }, "description": "Filter jobs by status. If omitted, all statuses are returned.", "example": "RUNNING" }, { "name": "time_range", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 24 }, "description": "Time range in hours to look back for jobs. Only jobs created within this window are returned. Defaults to 24 hours.", "example": 48 } ], "responses": { "200": { "description": "Jobs retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string" }, "jobName": { "type": "string" }, "jobQueue": { "type": "string" }, "jobQueueName": { "type": "string" }, "jobDefinition": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "integer" }, "startedAt": { "type": "integer" }, "stoppedAt": { "type": "integer" }, "statusReason": { "type": "string" }, "tags": { "type": "object" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" } } } } } }, "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 AWS Batch jobs" } } } } } } } } }, "/api/containers/batch/job_queue": { "get": { "operationId": "listBatchJobQueues", "tags": [ "AWS Batch" ], "summary": "List AWS Batch job queues visible to this EDH environment", "description": "Retrieves AWS Batch job queues that are tagged with the EDH visibility tag for this cluster.\nOnly queues with status VALID and state ENABLED are returned.\nIf a specific job queue name is provided, only that queue is returned (if it has the correct tag).\nOtherwise, all matching queues are returned with pagination handled automatically.\n", "security": [ { "socaAuth": [], "socaToken": [] } ], "parameters": [ { "name": "X-EDH-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-EDH-TOKEN", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "SOCA authentication token", "example": "abc123token456" }, { "name": "job_queue", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Name or ARN of a specific job queue to look up. If omitted, all visible job queues are returned.", "example": "my-job-queue" } ], "responses": { "200": { "description": "Job queues retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "array", "items": { "type": "object", "properties": { "jobQueueName": { "type": "string", "example": "my-job-queue" }, "jobQueueArn": { "type": "string", "example": "arn:aws:batch:us-east-1:123456789012:job-queue/my-job-queue" }, "jobQueueType": { "type": "string", "example": "STANDARD" }, "state": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "example": "ENABLED" }, "status": { "type": "string", "enum": [ "CREATING", "UPDATING", "DELETING", "DELETED", "VALID", "INVALID" ], "example": "VALID" }, "priority": { "type": "integer", "example": 1 }, "computeEnvironmentOrder": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "computeEnvironment": { "type": "string" } } } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } } }, "400": { "description": "Bad request - feature disabled or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Feature CONTAINERS_MANAGEMENT_BATCH is not enabled" } } } } } }, "401": { "description": "Unauthorized - invalid authentication", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not authorized" } } } } } }, "403": { "description": "Forbidden - IAM permission error", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "IAM permission error: the role does not have sufficient permissions to call batch:DescribeJobQueues." } } } } } }, "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 job queues. See log for more details" } } } } } } } } } }, "components": { "securitySchemes": { "edhAuth": { "type": "apiKey", "in": "header", "name": "X-EDH-USER", "description": "EDH username for authentication" }, "edhToken": { "type": "apiKey", "in": "header", "name": "X-EDH-TOKEN", "description": "EDH authentication token" } } }, "security": [ { "edhAuth": [], "edhToken": [] } ] }