.. title:: Developer API Developer API ======================== Kasm allows developers to extend the systems functionality through the use of our API. The API receives and sends data as Json. The API keys are created by the admin on the Developers tab. The API key and secret are needed to use the service API Keys -------- API Keys can be generated via the **Developers** tab. An **API_KEY** and **API_KEY_SECRET** will be automatically generated. .. figure:: /images/api/api_key.png :width: 90% :align: center **Creating an API Key** Authentication --------------- The API key and secret must be sent with all of the following requests as json data. .. sourcecode:: js { "api_key": "bMjMwTT0JKUQ" "api_key_secret": "KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS" } Base URL --------- https:///api/public/ Request Kasm ------------- Requesting a Kasm will create and start the container and assign a user to that Kasm. **Endpoint** /api/public/request_kasm **Arguments** user_id* *string*: An user Id can be specified to create the Kasm under that user. If no User ID is sent an anonymous user will be created and used for the Kasm. image_id* *string*: An image id can be sent for the desired image. Otherwise the default image sent on the group or user level will be used. enable_sharing* *boolean*: When the enable sharing flag is set to true the kasm will be created with sharing mode automatically enabled. * Optional **Response Format** kasm_id *string*: Returns the ID for the newly created Kasm. session_token *string*: Returns the token created for the user used in authorization of the Kasm. username *string*: Returns the username of the specified or newly created user. status *string*: Returns the operational status of the Kasm. Will be in Starting, Running or Stopped state. share_id *string*: Returns the Share id user_id *string*: Returns the user id of the specified or newly created user kasm_url *string*: Returns the url path to the specified kasm. This path must be appended to the current kasm server address. It is in the form of /#/connect/kasm/// Direct the user's browser to this url to access the Kasm session. This link should not be re-used for different users. **Example Request** .. sourcecode:: js { "api_key": bMjMwTT0JKUQ, "api_key_secret": KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS, "user_id": "8affcdbc16fc4910acb8a6dc268cd7ed", "image_id": "6a2d63fa8959412ca5fddd3890fb7223", "enable_sharing": True } **Example Response** .. sourcecode:: js { "kasm_id": "6d62ec66-3062-4f1d-b861-aeb3f5ca2390", "session_token": "b03bf84a-53fc-4934-85e4-c434461f1178", "username": "1d47uudwcynkd2su", "status": "starting", "share_id": "fe9770a4", "user_id": "8affcdbc16fc4910acb8a6dc268cd7ed", "kasm_url": "/#/connect/kasm/6d62ec66-3062-4f1d-b861-aeb3f5ca2390/8affcdbc16fc4910acb8a6dc268cd7ed/b03bf84a-53fc-4934-85e4-c434461f1178" } Get Kasm Status ---------------- After creating a kasm the status can be checked with get_kasm_status. This call also updates the session token for the user creating a new connection link and invalidating the old one. **Endpoint** /api/public/get_kasm_status **Arguments** user_id *string*: The user ID associated with the requested kasm. kasm_id *string*: The ID of the desired Kasm. **Response Format** current_time *string*: Returns the time at which the call was recieved in UTC. kasm *json object*: Returns the Kasm object containing all of the current information. kasm_url *string*: Returns the link path to the specified kasm. This path must be appended to the current kasm server address. It is in the form of /#/connect/kasm/// Direct the user's browser to this url to access the Kasm session. This link should not be re-used for different users. **Example Request** .. sourcecode:: js { "api_key": "bMjMwTT0JKUQ", "api_key_secret": "KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS", "user_id": "c7357f11eb4d47ad8021b5847d8415d8", "kasm_id": "d79ccb22-f6e7-4473-b8a2-a77da82278da" } **Example Response** .. sourcecode:: js { "current_time": "2019-11-06 19:18:22.345142", "kasm": { "memory": 768000000, "share_id": "89cc8cd3", "persistent_profile_mode": null, "server_id": "bc18a59727744be1a3419beff8a492b9", "container_id": "5ae27ba2c49d0e2e3b0a59f721a23d45d3b6b77c2c41a62c1ecafcb2c4b11291", "cores": 1.0, "operational_status": "running", "port_map": { "audio": { "port": 443, "path": "desktop/1aefe527-12dc-45/c6dc8361-5cd7-4dc1-9ee3-c33698f60864" }, "uploads": { "port": 443, "path": "desktop/1aefe527-12dc-45/44d0e9b7-5723-4fdf-a267-067a31c0fa77" }, "vnc": { "port": 443, "path": "desktop/1aefe527-12dc-45/775db8ad-819f-4b62-99fd-9d17af5ec569" } }, "image_id": "22222222222222222222222222222222", "token": "3893a81cdd4e45a789f6555e9ebf9986", "host": "172.21.0.8", "view_only_token": "cd17986413414852a2f67d59dc67bb08", "expiration_date": "2019-11-06 20:18:00.358531", "kasm_id": "d79ccb22f6e74473b8a2a77da82278da", "keepalive_date": "2019-11-06 19:18:00.358531", "container_ip": "172.21.0.9", "user_id": "c7357f11eb4d47ad8021b5847d8415d8", "client_settings": { "allow_persistent_profile": false, "enable_webp": false, "allow_kasm_sharing": true, "allow_kasm_audio": false, "allow_kasm_uploads": false, "allow_kasm_clipboard_seamless": false, "allow_kasm_downloads": false, "allow_point_of_presence": false, "allow_kasm_clipboard_down": false, "idle_disconnect": 20, "allow_kasm_clipboard_up": false, "kasm_audio_default_on": false }, "image": { "image_id": "22222222222222222222222222222222", "friendly_name": "Kasm Firefox", "name": "kasmweb/firefox:1.7.0", "image_src": "img/thumbnails/firefox.png" }, "port": 443, "is_persistent_profile": false, "hostname": "192.168.1.216", "point_of_presence": null, "start_date": "2019-11-06 19:18:00.358521" }, "kasm_url": "/#/connect/kasm/d79ccb22f6e74473b8a2a77da82278da/c7357f11-eb4d-47ad-8021-b5847d8415d8/7cbfbf23-1354-45f0-9248-face13ce10da" } Join Kasm --------- Join Kasm returns the status of the shared kasm and a join url to connect to the Kasm session as a view-only user. **Endpoint** /api/public/join_kasm **Arguments** user_id* *string*: The user ID used to create the join link. If none supplied an anonymous user will be created. share_id *string*: The share ID of the desired kasm. * Optional **Response Format** current_time *string*: Returns the time at which the call was received in UTC. kasm *json object*: Returns the Kasm object containing all of the current information. kasm_url *string*: Returns the link path to the specified shared kasm. This path must be appended to the current kasm server address. It is in the form of /#/connect/join/// Direct the user's browser to this url to access the Kasm session. This link should not be re-used for different users. session_token *string*: Returns the token created for the user used in authorization of the Kasm. username *string*: Returns the username of the specified or newly created user. user_id *string*: Returns the user ID of the specified or newly created user. **Example Request** .. sourcecode:: js { "api_key": "bMjMwTT0JKUQ", "api_key_secret": "KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS", "user_id":"c7357f11eb4d47ad8021b5847d8415d8", "share_id":"89cc8cd3" } **Example Response** .. sourcecode:: js { "kasm_url": "/#/connect/join/89cc8cd3/c7357f11eb4d47ad8021b5847d8415d8/070fce1f-86c6-4e05-9b10-935632acb8ce", "kasm": { "port_map": { "vnc": { "port": 443, "path": "desktop/1aefe527-12dc-45/775db8ad-819f-4b62-99fd-9d17af5ec569" }, "audio": { "port": 443, "path": "desktop/1aefe527-12dc-45/c6dc8361-5cd7-4dc1-9ee3-c33698f60864" } }, "port": 443, "kasm_id": "d79ccb22f6e74473b8a2a77da82278da", "user": { "username": "heznaimagjrza7rm" }, "share_id": "89cc8cd3", "hostname": "192.168.1.216", "image": { "image_id": "22222222222222222222222222222222", "friendly_name": "Kasm Firefox", "name": "kasmweb/firefox:1.7.0", "image_src": "img/thumbnails/firefox.png" }, "client_settings": { "allow_kasm_clipboard_down": false, "allow_persistent_profile": false, "enable_webp": false, "allow_kasm_clipboard_seamless": false, "allow_kasm_uploads": false, "idle_disconnect": 20, "allow_kasm_sharing": true, "allow_kasm_audio": false, "allow_kasm_downloads": false, "allow_point_of_presence": false, "allow_kasm_clipboard_up": false, "kasm_audio_default_on": false }, "host": "172.21.0.8", "view_only_token": "cd17986413414852a2f67d59dc67bb08" }, "session_token": "070fce1f-86c6-4e05-9b10-935632acb8ce", "user_id": "c7357f11eb4d47ad8021b5847d8415d8", "username": "heznaimagjrza7rm", "current_time": "2019-11-06 19:59:10.544396" } Destroy Kasm ------------ Destroy kasm can be called to destroy a Kasm. **Endpoint** /api/public/destroy_kasm **Arguments** user_id *string*: The user ID used of the kasm owner. kasm_id *string*: The ID of the kasm to be destroyed. **Response Format** If empty response is sent the Kasm was successfully deleted. **Example Request** .. sourcecode:: js { "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8", "api_key": "JgcKL1glyQrS", "user_id": "4d892bf39321494da9a159178972c147", "api_key_secret": "KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS" } **Example Response** .. sourcecode:: js {} Get Images ------------ Retrieve a list of available images. **Endpoint** /api/public/get_images **Arguments** None **Response Format** images *Json Object*: Contains Image information including Image_id and name. **Example Request** .. sourcecode:: js { "api_key": "JgcKL1glyQrS", "api_key_secret": "XnPMU24uqgLPj4C1jm6MOXnlUBrDfqog" } **Example Response** .. sourcecode:: js { "images": [ { "restrict_to_network": false, "memory": 768000000, "zone_name": null, "x_res": 800, "description": "Single-Application : Chrome", "image_id": "b483f0a4fb6546f79064f9b6759758cb", "persistent_profile_path": null, "friendly_name": "Kasm Chrome", "volume_mappings": {}, "restrict_to_zone": false, "docker_token": null, "persistent_profile_config": {}, "cores": 1.0, "docker_registry": "https://index.docker.io/v1/", "available": true, "run_config": { "hostname": "kasm" }, "imageAttributes": [ { "image_id": "b483f0a4fb6546f79064f9b6759758cb", "attr_id": "11cd3b92d73c4caaa84c70e75190ec25", "name": "vnc", "category": "port_map", "value": "6901/tcp" }, { "image_id": "b483f0a4fb6546f79064f9b6759758cb", "attr_id": "ec1531322190445db70d10c31766503a", "name": "audio", "category": "port_map", "value": "4901/tcp" }, { "image_id": "b483f0a4fb6546f79064f9b6759758cb", "attr_id": "3634ba1144bc4f64a932a561983c64f5", "name": "uploads", "category": "port_map", "value": "4902/tcp" } ], "docker_user": null, "restrict_to_server": false, "enabled": true, "name": "kasmweb/chrome:develop", "zone_id": null, "y_res": 600, "server_id": null, "network_name": null, "exec_config": { "first_launch": { "environment": { "LAUNCH_URL": "" }, "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'" }, "go": { "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'" } }, "hash": null, "image_src": "img/thumbnails/chrome.png" } ] } Get Kasms ------------ Retrieve a list of Live Kasms. **Endpoint** /api/public/get_kasms **Arguments** None **Response Format** kasms *Json Object*: Contains Kasm information including Image, status and user data. **Example Request** .. sourcecode:: js { "api_key": "JgcKL1glyQrS", "api_key_secret": "XnPMU24uqgLPj4C1jm6MOXnlUBrDfqog" } **Example Response** .. sourcecode:: js { "kasms": [ { "memory": 768000000, "view_only_token": "f7bba0c1810b44f3a940ba5769d74f1c", "cores": 1.0, "start_date": "2019-11-07 18:52:29.890857", "keepalive_date": "2019-11-07 19:36:34.848838", "user_id": "2dd42cf552164f6d973ba36bdb9217be", "user": { "username": "bh6khsgaqw98en5f" }, "container_id": "38e116944dc1a355ed037008d6f0f1ca3b084b6bdf9c8968832bdd231aed7102", "port": 443, "image": { "image_id": "b483f0a4fb6546f79064f9b6759758cb", "name": "kasmweb/chrome:develop", "friendly_name": "Kasm Chrome", "image_src": "img/thumbnails/chrome.png" }, "port_map": { "uploads": { "path": "desktop/fac1a48e-5aaf-4a/6c8dd20e-914c-4004-a5a6-46cd10db7c00", "port": 443 }, "vnc": { "path": "desktop/fac1a48e-5aaf-4a/ea9d60d7-0b60-44e6-8732-f08a2c77ec98", "port": 443 }, "audio": { "path": "desktop/fac1a48e-5aaf-4a/989908d6-1cf4-4b4f-aaee-c6a87c7bbbb1", "port": 443 } }, "expiration_date": "2019-11-07 20:36:34.848838", "share_id": null, "kasm_id": "cae4a13bf6ab4de99d06a54a2ee437ce", "host": "172.18.0.8", "token": "8728609ddf0b45bb9585ea7d5e279cfd", "operational_status": "running", "is_persistent_profile": false, "persistent_profile_mode": null, "point_of_presence": null, "image_id": "b483f0a4fb6546f79064f9b6759758cb", "container_ip": "172.18.0.9", "server_id": "abeb6f47f4ee4e25a1b9e641249edd40", "server": { "zone_name": "default", "provider": "hardware", "hostname": "proxy", "port": 443 }, "hostname": "192.168.1.216", "client_settings": { "allow_kasm_uploads": false, "kasm_audio_default_on": false, "allow_kasm_clipboard_seamless": false, "idle_disconnect": 20, "allow_kasm_sharing": false, "allow_kasm_downloads": false, "enable_webp": false, "allow_persistent_profile": false, "allow_kasm_clipboard_up": false, "allow_point_of_presence": false, "allow_kasm_clipboard_down": false, "allow_kasm_audio": false } } ], "current_time": "2019-11-07 20:18:17.876063" } Errors ------ In the event of an error processing an api request, Kasm will respond with an **error_message** in the body of the json response **Example Response** .. sourcecode:: js {"error_message": ""}