General
/v3/api
Get configuration information. This information does not require a log in
Parameters
None
Result
{
"result": {
"version": 3, /* the version string */
"serverId": "STRING_VALUE", /* server id of the server you are connecting to */
"port": 3000, /* HTTP port */
"httpsport": 3443 /* HTTPS port */
"hostname": "STRING_VALUE", /* hostname of the server */
"servers": ["SERVER_ID_1","SERVER_ID_2","SERVER_ID_3", ...] /* Array of server ids you can connect to */,
"ssh": {
"basic": false, /* force basic ssh authentication */
"publicKey": true, /* enable publicKey authentication */
"hidePasswordField": false /* hide the password field */
}
}
}
/v3/api/config
/v3/api/xrdp/config
Get the XRDP default settings (we should change the way we get this)
User
/v3/api/user/login
Parameters
{
"username": "STRING_VALUE", /* <required> SSH username */
"password": "STRING_VALUE", /* SSH Password */
"serverId": "STRING_VALUE", /* serverId of the host you want to log in to (found by calling /api/server) */
"usePK": false, /* enable public-key authentication */
"basic": false /* use basic authentication. See Web Client Authentication */
}
Result
JSON object. The object contains different members depending on the authentication stage. Authentication has not completed until the ‘success’ stage has been reached.
{
"result": {
"stage": "public-key" | "keyboard-interactive" | "password" | "success", /* authentication stage */
"token": "STRING_VALUE", /* connection token which is required during authentication */
"prompt": "STRING_VALUE", /* (stage keyboard-interactive only) text description of the prompt */
"host": "STRING_VALUE", /* hostname of the server the user is authenticating on */
}
Stage: public-key
Next Step: Send the public key to the server
Stage: keyboard-interactive
Next Step: The prompts parameter contains an array of prompts that the user should make responses to. Send the array of responses to /api/login/keyboard-interactive/:token
Stage: password
Next Step: Password based authentication
Stage: success
User has successfully logged in and can now issue api commands
/v3/api/user/login/public-key
Send the public key to the server during authentication
Parameters
{
"publicKey": "STRING_VALUE" /* Base64 encoded public key of the SSH key */
}
The format of the Public Key is as follows
4 bytes – unsigned int: length X of string to come
X bytes – string: this will be ‘ssh-rsa’ (7 chars)
4 bytes – unsigned int: length Y of byte array
Y bytes – bigint of ‘e’
4 bytes – unsigned int: length Z of byte array
Z bytes – bigint of ‘n’
Result
JSON object of the authentication stage. See /api/login
/v3/api/user/login/keyboard-interactive
Answer them prompt of the keyboard-interactive stage
For more information see Login process state machine and /api/login
Parameters
{
"answer": "STRING_VALUE" /* answer to the prompt given by /api/login or /api/keyboard-interactive */
}
Result
JSON object of the authentication stage. See /api/login
/v3/api/user/login/password
Answer the prompt of the password stage
For more information see Login process state machine and /api/login
Parameters
{
"password": "STRING_VALUE" /* SSH Password */
}
Result
JSON object of the authentication stage. See /api/login
/v3/api/user/login/public-key/signed
Sign the data and send to the server during authentication
Parameters
{
"signature": "STRING_VALUE" /* Base64 encoded signed data */
}
Result
JSON object of the authentication stage. See /api/login
/v3/api/user/profile
Get the user’s profile
Parameters
None
Result
{
"result": {
"token": "STRING_VALUE", /* User's authentication token */
"login": "STRING_VALUE", /* User's username */
"hostname": "STRING_VALUE", /* Hostname where the user is logged in */
"provider": "ssh" | "okta" | "link", /* authentication method used to log in */
"authenticated": true, /* User has authenticated to the server and can send messages */
"loggedIn": true, /* Server has responded back completing the authentication process */
"groups": ["group1", "group2", ..., "groupN"], /* Array of Linux groups associated with the username */
"email": "STRING_VALUE", /* Email address (if found) */
"firstName": "STRING_VALUE", /* User's first name */
"lastName": "STRING_VALUE", /* User's last name */
}
}
/v3/api/user/logout
Logs user out and deletes the token
Parameters
None
Result
{
"result": null
}
/v3/api/user/admin
Returns a result if the user is an admin
Parameters
None
Result
{
"result": null
}
/v3/api/user/keepalive
Sends a keepalive call to keep the user session open
Parameters
None
Result
{
"result": null
}
Session
/v3/api/session/connect
Reconnect to an existing session
Parameters
{
"id": "STRING_VALUE" /* <required> Session Id */
"params": { /* user parameters to set */
"key1": "value1",
"key2": "value2",
...
}
}
Result
{
"result": {
"geometry": "1024x768", /* geometry of the session */
"id": "STRING_VALUE", /* session id */
"login": "STRING_VALUE", /* username who started the session */
"params": { /* user parameters that have been set */
"key1": "value1",
"key2": "value2",
},
"password": "STRING_VALUE", /* one-time password that will be used to connect to the session */
"port": 40000, /* local port the session is listening on */
"windowMode": "rootless" | "desktop" /* window mode of the session */
}
}
/v3/api/session/disconnect
Disconnect all users from the session
Parameters
{
"id": "STRING_VALUE" /* <required> Session Id */
}
Result
{
"result": null
}
/v3/api/session/exec
/v3/api/session/list
List the user’s currently running sessions
Parameters
{
"start": 0. /* Starting session object */
"sortBy": "STRING_VALUE", /* member to sort by (it will also check members in “params”) */
"sortReverse": false, /* return session objects in reverse sort order */
"limit": Infinity, /* maximum number of session objects to return */
"filter": ["FILTER_STRING_1", "FILTER_STRING_2", ...] /* filter session objects */
}
FILTER_STRING is defined as follows "name==value1,value2,valueN"
name -- the member name to filter on
value1,value2,valueN -- comma separated list of values which acts as an OR
You can have multiple filters which act as AND
Result
{
"result": [ /* Array of Session Objects */
{
"appPid": 1234, /* Pid of the process started from command */
"clients": 0, /* number of clients currently connected */
"command": "STRING_VALUE", /* initial command execed when the session was launched */
"cpuPercentage": 25, /* CPU Percentage parameter when the session was started */
"disconnectTimeout": 0, /* disconnectTimeout parameter when the session was started */
"display": ":100", /* DISPLAY number of the session */
"geometry": "1024x768", /* widthxheight of the session */
"hostname": "STRING_VALUE", /* hostname of the machine the session is running on */
"id": "STRING_VALUE", /* Session Id */
"lastConnect": "TIMESTAMP", /* timestamp when the session was connected to */
"lastDisconnect": "TIMESTAMP", /* timestamp when the session was disconnected from */
"login": "STRING_VALUE", /* name of the user who started the session */
"params":{ /* user parameters that have been set */
"key1": "value1",
"key2": "value2"
...
}
"serverId": "STRING_VALUE", /* id of the FastX server running the session */
"serverPid": 5678, /* Pid of the session process */
"sharing": true, /* Sharing parameter when the session was started */
"started": "TIMESTAMP", /* timestamp when the session was started */
"videoRam": 128000, /* Video RAM parameter when the session was started */
"windowMode": "rootless" | "desktop", /* window mode of the session */
}
]
}
/v3/api/session/list/count
Return the number of user sessions
Parameters
None
Result
{
"result": 0 /* Number of running sessions of the user */
}
/v3/api/session/log
View a session’s log file
Parameters
{
"id": "STRING_VALUE" /* <required> Session Id */
}
Result
{
"result": {
//TODO
}
}
/v3/api/session/params
Add custom parameters to the session
Parameters
{
"id": "STRING_VALUE" /* <required> Session Id */
"params": { /* key/value pairs of the parameters */
"key1": "value1",
"key2": "value2",
...
}
}
Note: Set a key to an empty string "" to delete the parameter
Result
{
"result": { /* the user parameters */
"key1": "value1",
"key2": "value2",
...
}
}
/v3/api/session/schedule
/v3/api/session/screenshot
Take a screenshot of the running session
Parameters
{
"id": "STRING_VALUE", /* <required> session id */
"width": 800, /* screenshot width in pixels */
"height": 600, /* screenshot height in pixels */
"format": “png” | “jpeg”, /* Specify image format default “png” */
"keep_aspect": 1 | 0 /* keep aspect ratio when reducing image size */
"geometry": "widthxheight" /* specify the geometry in pixels (same as using width and height members) */
}
Result
{
"result": {
"src": "STRING_VALUE" /* dataUrl of the image data */
}
}
/v3/api/session/shortcut
Connect to a session which has the shortcut parameter or start a new session if no session exists
Parameters
{
"id": "STRING_VALUE" /* <required> Bookmark id to search for */
}
Result
Connect Object. See connect
/v3/api/session/start
Start a new session
Parameters
{
"command": "STRING_VALUE", /* <required> Command to execute */
"geometry": "1024x768" | "rootless", /* geometry of the session */
"id": "STRING_VALUE", /* specify the id of the session */
"name": "STRING_VALUE" /* Set the name parameter */
"params: { /* user defined parameters */
"key1": "value1",
"key2": "value2",
...
}
}
Result
Connect Object. See connect
/v3/api/session/start/bookmark
Start a new session using a bookmark id
Parameters
{
"id": "STRING_VALUE", /* <required> Bookmark id */
}
Result
Connect Object. See connect
/v3/api/session/terminate
Terminate a session
Parameters
{
"id": "STRING_VALUE" /* <required> Session Id */
}
Result
{
"result": null
}
Bookmark
/v3/api/bookmark/list
List the bookmarks, history, and suggestions
Parameters
None
Result
{
"result": {
"suggestions":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...], /* array of global bookmarks */
"bookmarks":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...], /* array of user defined bookmarks */
"history":[BOOKMARK_OBJECT_1,BOOKMARK_OBJECT_2,...], /* array history */
}
}
BOOKMARK_OBJECT is defined as follows
{
"id": "STRING_VALUE", /* <required> bookmark id */
"command": "STRING_VALUE", /* <required> command to execute */
"name": "STRING_VALUE", /* bookmark display name */
"geometry": "widthxheight" | "rootless", /* geometry of the bookmark */
"tags": ["tag1","tag2", ..., "tagN"] /* array of tag strings */
}
/v3/api/bookmark/edit
Create or edit a user defined bookmark
Parameters
{
"id": "STRING_VALUE", /* <required> bookmark id */
"command": "STRING_VALUE", /* <required> command to execute */
"name": "STRING_VALUE", /* bookmark display name */
"geometry": "widthxheight" | "rootless", /* geometry of the bookmark */
"tags": ["tag1","tag2", ..., "tagN"] /* array of tag strings */
}
Result
See bookmark/list
/v3/api/bookmark/delete
Delete a user defined bookmark or a history object.
Parameters
{
"id": "STRING_VALUE" /* <required> bookmark id */
}
Result
See bookmark/list
Share
/v3/api/share/list
Get the sharing keys of the session
Parameters
{
"id": "STRING_VALUE" /* <required> session id */
}
Result
{
"result": [
{
"id": "STRING_VALUE", /* session id */
"key": "STRING_VALUE", /* sharing key */
"perms": ["viewer", "granter"], /* array of permissions for the key */
"timeout": 60, /* number of seconds a user has to connect with the share password */
},
...
]
}
/v3/api/share/connect
Parameters
{
"id": "STRING_VALUE", /* <required> session id */
"key": "STRING_VALUE" /* <required> share key */
}
Result
connect object
/v3/api/share/edit
Edit a share key
Parameters
{
"id": "STRING_VALUE", /* <required> session id */
"key": "STRING_VALUE" /* <required> share key to edit */
"perms": ["viewer","granter"], /* <required> array of share permissions for the key */
}
Result
share/list object
/v3/api/share/email
/v3/api/share/delete
Delete a sharing key
Parameters
{
"id": "STRING_VALUE", /* <required> session id */
"key": "STRING_VALUE" /* <required> share key to delete */
}
Result
share/list object
/v3/api/share/reset
Delete the sharing keys of the session and disconnect all users
Parameters
{
"id": "STRING_VALUE", /* <required> session id */
"perms": ["viewer", "granter"] /* Array of permissions. Delete a sharing key that contains a permission in the array.
An empty array deletes all permissions. */
}
Result
share/list object
System
/v3/system/session/profile
/v3/system/session/count
/v3/system/session/list
/v3/system/server/list