Developer API

The Kasm Workspaces Developer API can be leveraged to extend the systems functionality and/or integrate with an exiting platform. Integrators interface with the API to create and manage sessions, users and groups.

Integration Workflow

Code-less Integration Options

Integrators are encouraged to review Session Casting which provides an easy way to expose access to Kasm sessions via special URLs.

API Keys

API Keys can be generated via the Settings -> Developers -> Add API Key. An API_KEY and API_KEY_SECRET will be automatically generated. Administrators can optionally set an expiration date for the API key.

Creating an API Key

Authentication

The API key and secret must be sent with all of the following requests as json data.

{
    "api_key": "bMjMwTT0JKUQ"
    "api_key_secret": "KUNAvRw4KLHGmldBxhRUD5sAhWkvJVzS"
}

Permissions

By default, API keys have no permissions. To define permissions for API keys, edit the API Key configuration and go to the permissions tab. The Read Only setting on the API key overrides permissions defined and is enforced via a separate mechanism.

Two permissions are needed to perform actions as another user with the DevAPI, such as creating a Workspace session for a user. The Users Auth Session permission is require in order to run requests as another user and the User permission is needed to run standard user API calls.

API Key Permissions

The following table lists the permissions and descriptions of each permission.

Name	Description
User	Default level of permissions for normal users.
Global Admin	Global Administrator with all permissions.
Users View	View users and user information.
Users Modify	Modify existing users.
Users Create	Create new users.
Users Delete	Delete exiting users.
Users Modify Admin	Modify users with Global Admin permissions.
Users Auth Session	Login and logout on behalf of another user.
Groups View	View groups, group members, and group settings.
Groups Modify	Modify group members and settings.
Groups Create	Create new groups.
Groups Delete	Delete existing groups.
Groups View IfMember	View groups you are a member of, excluding system groups.
Groups Modify IfMember	Modify groups you are a member of, excluding system groups.
Groups View System	View groups, group members and group settings of system defined groups.
Groups Modify System	Modify group members and settings of system groups.
Groups Delete System	Delete a system group.
Agents View	View agents and agent settings.
Agents Modify	Modify agent settings.
Agents Create	Create agents.
Agents Delete	Delete existing agents.
Staging View	View staging list and stage configuration settings.
Staging Modify	Modify existing staging settings.
Staging Create	Create new staging configurations.
Staging Delete	Delete existing staging configurations.
Casting View	View casting list and casting configuration settings.
Casting Modify	Modify existing casting settings.
Casting Create	Create new casting configurations.
Casting Delete	Delete existing casting configurations.
Sessions View	View all user sessions.
Sessions Modify	Perform modifications to a session of another user.
Sessions Delete	Delete the session of another user.
Session Recordings View	View user session recordings.
Images View	View images
Images Modify	Modify image configurations.
Images Create	Create new images.
Images Delete	Delete existing images.
Images Modify Resources	Modify image resource settings, such as CPU and Memory settings.
DevAPI View	View developer API list.
DevAPI Modify	Modify developer API configurations.
DevAPI Create	Create a new developer API key.
DevAPI Delete	Delete an existing developer API key.
Webfilters View	View webfilters
Webfilters Modify	Modify existing webfilters
Webfilters Create	Create a new webfilter.
Webfilters Delete	Delete an existing webfilter
Brandings View	View branding configurations.
Brandings Modify	Modify existing branding configurations.
Brandings Create	Create new branding configurations.
Brandings Delete	Delete existing branding configurations.
Settings View	View global settings.
Settings Modify	Modify global settings in all categories.
Settings Modify Auth	Modify global settings in the authentication category.
Settings Modify Cast	Modify global settings in the casting category.
Settings Modify Images	Modify global settings in the images category.
Settings Modify License	Modify global settings in the license category.
Settings Modify Logging	Modify global settings in the logging category.
Settings Modify Manager	Modify global settings in the manager category.
Settings Modify Scale	Modify global settings in the scale category.
Settings Modify Subscription	Modify global settings in the subscription category.
Settings Modify Filter	Modify global settings in the filter category.
Settings Modify Storage	Modify global settings in the storage category.
Settings Modify Connections	Modify global settings in the connections category.
Settings Modify Theme	Modify global settings in the theme category.
Auth View	View LDAP/OIDC/SAML configurations.
Auth Modify	Modify LDAP/OIDC/SAML configurations.
Auth Create	Create LDAP/OIDC/SAML configurations.
Auth Delete	Delete LDAP/OIDC/SAML configurations.
Licenses View	View licenses.
Licenses Create	Add new licenses.
Licenses Delete	Delete licenses.
System View	View system information.
System Export Schema	Export system schema.
System Import Data	Import system data.
System Export Data	Export system data.
Reports View	View system reports and logging. Warning: Providing access to logs can provide a lot of potentially sensitive information.
Managers View	View the managers.
Managers Modify	Modify existing managers.
Managers Create	Create a new manager.
Managers Delete	Delete existing managers.
Zones View	View Zones and Zone settings.
Zones Modify	Modify Zone settings.
Zones Create	Create new Zones.
Zones Delete	Delete existing Zones.
Companies View	View companies.
Companies Modify	Modify existing company.
Companies Create	Create a new company.
Companies Delete	Delete an existing company.
Connection Proxy View	View connection proxies.
Connection Proxy Modify	Modify connection proxies.
Connection Proxy Create	Create a connection proxy.
Connection Proxy Delete	Delete an existing connection proxy.
Physical Tokens View	View physical 2FA tokens.
Physical Tokens Modify	Assign/Unassign physical 2FA tokens.
Physical Tokens Create	Import or create physical 2FA tokens.
Physical Tokens Delete	Delete a physical 2FA token.
Servers View	View servers.
Servers Modify	Modify existing servers.
Servers Create	Create new servers.
Servers Delete	Delete servers.
Server Pools View	View server pools.
Server Pools Modify	Modify server pools.
Server Pools Create	Create a new server pool.
Server Pools Delete	Delete a server pool.
Autoscale View	View auto scale configurations.
Autoscale Modify	Modify an existing auto scale configuration.
Autoscale Create	Create a new auto scale configuration.
Autoscale Delete	Delete auto scale configurations.
VM Provider View	View VM Provider configurations.
VM Provider Modify	Modify VM Provider configurations.
VM Provider Create	Create new VM Provider configurations.
VM Provider Delete	Delete VM Provider configurations.
Autoscale Schedule View	View an auto scale schedule.
Autoscale Schedule Modify	Modify an auto scale schedule.
Autoscale Schedule Create	Create an auto scale schedule.
Autoscale Schedule Delete	Delete an auto scale schedule.
DNS Providers View	View DNS provider configurations.
DNS Providers Modify	Modify DNS provider configurations.
DNS Providers Create	Create new DNS Provider configurations.
DNS Providers Delete	Delete DNS Provider configurations.
Registries View	View Workspace Registries.
Registries Modify	Modify existing Workspace Registries.
Registries Create	Add new Workspace Registries
Registries Delete	Delete a Workspace Registry
Storage Providers View	View Storage Providers.
Storage Providers Modify	Modify existing Storage Providers.
Storage Providers Create	Create new Storage Providers.
Storage Providers Delete	Delete an existing Storage Provider.

Permission Changes

A user’s permissions are embedded in their session token, which is generated on login. A user’s token lifetime is controlled by the Session Lifetime global setting. The UI will get a new session token every 5 minutes. The fastest way to get new permissions to apply, is to have the user log out and log back in, otherwise, the change will apply generally within 5 minutes.

Permission Dependencies

While most permissions can stand alone, there are dependencies between some permissions. Generally, a Modify, Create, and/or Delete permission will need the corresponding View permission. The following are additional permission dependencies, which means you will need to grant multiple permissions to have the desired effect.

• Licenses View requires System View

• Permissions View requires Groups View

• Registries View requires Images View, System View, and Agents View

• Autoscale View requires Server Pools View

• Autoscale Schedule View requires Server Pools View

• DNS Providers View requires Server Pools View

• VM Providers View requires Server Pools View and Autoscale View

• Users Delete requires Sessions Delete if the target user has running sessions and Users Modify

• Users Delete requires Users Modify Admin to delete a user that has the Global Admin permission

There are many cases where multiple permissions are not required, however, certain UI elements will be hidden if the user does not have the permissions to view them. For example, a user may have permissions to View Images, however, they may not have permissions to View Servers. If the user goes to view an individual Workspace Image that targets a Server, they will not see the drop down to view or edit the server the image is targeting.

Special Permissions

There are more available permissions around groups, beyond the basic View, Create, Modify, and Delete. The Groups View IfMember and Groups Modify IfMember allow a user to view or modify a group if they are a member of that group. This does not extend to built-in system groups (All Users and Administrator). To edit or view System groups, they will also need the Groups View/Modify System permission.

There is an additional permission that protects modification of users with the Global Admin permission. In order to modify a Global Admin, the user requesting the modification must themselves be a Global Admin or have the User Modify Admin permission.

There are two permissions that allow modifications to Workspace Images, Images Modify and Images Modify Resources. The Images Modify allows modification of all Image settings except those that would modify the physical/virtual compute resources. The following settings require the Images Modify Resources permission to edit:

• GPU Count

• Cores

• Memory

• CPU Allocation Method

• Uncompressed Image Size

• Docker Registry

• Docker Registry Username

• Docker Registry Password

• Hash

• Volume Mappings

• Docker Run Config Override

• Docker Exec Config

Base URL

All Dev APIs documented here are under the path api/public/:

https://<kasm_server>/api/public/

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

{"error_message": "<error details>"}

Users

Create User

Create a new user.

Permission Required: Users Create

POST /api/public/create_user

Example request:

JSON

{
     "api_key":"{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "username" : "test_user1@example.com",
         "first_name" : "Bob",
         "last_name" : "Williams",
         "locked": false,
         "disabled": false,
         "organization": "example",
         "phone": "123-456-7890",
         "password": "3UPKGg7g!a9g2@39v6"
     }
 }

Example response:

{
    "user": {
        "first_name": "Bob",
        "username": "test_user1@example.com",
        "realm": "local",
        "last_name": "Williams",
        "phone": "123-456-7890",
        "last_session": null,
        "notes": null,
        "user_id": "50faa5439c574b518cd868dac9256e4b",
        "groups": [
            {
                "name": "All Users",
                "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
            }
        ],
        "disabled": false,
        "organization": "example",
        "locked": false
    }
}

Get User

Retrieve the properties of an existing user. target_user.user_id or target_user.username can be passed

Permission Required: Users View

POST /api/public/get_user

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "4bbb6998064a4d1ea4685f3cdd05feb4",
         "username": "user@kasm.local"
     }
 }

Example response:

{
    "user": {
        "user_id": "4bbb6998064a4d1ea4685f3cdd05feb4",
        "username": "user@kasm.local",
        "locked": false,
        "last_session": "2020-11-09 14:41:33.578622",
        "groups": [
            {
                "name": "All Users",
                "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
            }
        ],
        "first_name": null,
        "last_name": null,
        "phone": null,
        "organization": null,
        "notes": null,
        "kasms": [
            {
                "kasm_id": "28cfc2a510bb424cad18e571f11ee26c",
                "start_date": "2020-11-09 14:46:42.321900",
                "keepalive_date": "2020-11-09 14:46:43.140623",
                "expiration_date": "2020-11-09 15:46:43.140623",
                "server": {
                    "server_id": "36e2aeff0e02445db26a521c9c85f1c1",
                    "hostname": "proxy",
                    "port": 443
                }
            }
        ],
        "realm": "local",
        "two_factor": false,
        "program_id": null,
        "hash": "9fdfdaad0098cdd8a466b2badbaf962e40214affb07596a6e9d776a409793780"
    }
}

Get Users

Retrieve the list of users registered in the system.

Permission Required: Users View

POST /api/public/get_users

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
 }

Example response:

{
    "users": [
        {
            "kasms": [],
            "company": {},
            "username": "user@kasm.local",
            "locked": false,
            "realm": "local",
            "phone": null,
            "first_name": null,
            "notes": null,
            "user_id": "57e8fc1a-fa86-4ff4-9474-60d9831f42d5",
            "last_session": "2020-11-12 14:29:25.808258",
            "groups": [
                {
                    "name": "All Users",
                    "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
                }
            ],
            "disabled": true,
            "organization": null,
            "last_name": null
        },
        {
            "kasms": [],
            "company": {},
            "username": "admin@kasm.local",
            "locked": false,
            "realm": "local",
            "phone": null,
            "first_name": null,
            "notes": null,
            "user_id": "4acb13bf-1215-4972-9f0d-8c537d17f2da",
            "last_session": "2020-11-12 14:35:19.700863",
            "groups": [
                {
                    "name": "All Users",
                    "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
                },
                {
                    "name": "Administrators",
                    "group_id": "31aa063c670648589533d3c42092d02a"
                }
            ],
            "disabled": false,
            "organization": null,
            "last_name": null
        }
    ]
}

Update User

Update the properties of an existing user.

Permission Required: Users Modify and Users Modify Admin to update users with Global Admin permission.

POST /api/public/update_user

Example request:

JSON

{
     "api_key":"{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "4acb13bf-1215-4972-9f0d-8c537d17f2da",
         "username" : "test_user1@example.com",
         "first_name" : "Bob",
         "last_name" : "Williams",
         "locked": false,
         "disabled": false,
         "organization": "example",
         "phone": "123-456-7890",
         "password": "3UPKGg7g!a9g2@39v6"
     }
}

Example response:

{
    "user": {
        "first_name": "Bob",
        "username": "test_user1@example.com",
        "realm": "local",
        "last_name": "Williams",
        "phone": "123-456-7890",
        "last_session": null,
        "notes": null,
        "user_id": "50faa5439c574b518cd868dac9256e4b",
        "groups": [
            {
                "name": "All Users",
                "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
            }
        ],
        "disabled": false,
        "organization": "example",
        "locked": false
    }
}

Delete User

Delete an existing user. If the user has any existing Kasm sessions, deletion will fail. Set the force option to true to delete the user’s sessions and delete the user.

Permission Required: Users Delete and Users Modify, Users Modify Admin is required to delete a user with Global Admin permission.

POST /api/public/delete_user

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "4bbb6998064a4d1ea4685f3cdd05feb4"
     },
     "force": false
}

Example response:

{}

Logout User

Logout all sessions for an existing user.

Permission Required: Users Auth Session

POST /api/public/logout_user

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "4bbb6998064a4d1ea4685f3cdd05feb4"
     }
}

Example response:

{}

Get User Attributes

Get the attribute (preferences) settings for an existing user.

Permission Required: Users View

POST /api/public/get_attributes

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0",
     }
 }

Example response:

{
    "user_attributes": {
        "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCjy8izTD7DlykY0J7iiBn4ysIRqLBwM94ZnjfYH1XAo96ay3grQjSDl5f4u0hrVz6bX62kgPlm9QvTqceNZ+rC/anKp/9nQIrDM6y2W3jNUM6Eo+Ryh7xIOII2lnCbtE/M4urX4lZx3oB2JyIMSIN3yvKUBCSht5FsFabguc8i+nwLvXjmnZx+fcR2/BNcIM9UjCfYBjLFd1XFER7aIXjRy7y2MJQHCFrzhDThNllJ6C1oMZiBsBJ5lXpBmlim80A9IvcW7YBgsAQoqLgrCvRc7IdENTzPAyyhODE/ib5SkwK/peUuCRM+SZnPpUGlv9emLXVjrg5P+TPO/N/v7lyj",
        "show_tips": false,
        "user_id": "57e8fc1afa864ff4947460d9831f42d5",
        "toggle_control_panel": false,
        "chat_sfx": true,
        "user_attributes_id": "ef7b72db25b14ab1ac98ac19676ac93f",
        "default_image": null,
        "auto_login_kasm": null
    }
}

Update User Attributes

Update a users attributes.

Permission Required: Users Modify and Users Modify Admin if the target user has the Global Admin permission.

POST /api/public/update_user_attributes

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user_attributes": {
         "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0",
         "auto_login_kasm": false,
         "default_image": "b2609fbf72954b20a56c1fe502aa2c41",
         "show_tips": false,
         "toggle_control_panel": false
     }
 }

Example response:

{}

Kasms

Workflow

The following diagram outlines the basic workflow for requesting a session and verifying its status before delivering it to the end user.

Session Workflow

1. The end-user initiates an action to create a Kasm session.

2. The integrator app backend requests a session from Kasm via /api/request_kasm.

3. The integrator app calls /api/get_kasm_status to interrogate operational_status or kasm.operational_status. The session should only be considered ready for user consumption if the kasm.operational_status is running. If the status is not running, the integrator should poll at regular intervals to retrieve the updated status.

Note

A number of factors may delay the session from reaching the running status quickly, such as loading S3 Persistent Profiles , or waiting for Autoscaled compute to fully provision. Integrators should be aware of these factors and tune the system accordingly to achieve an acceptable user experience.

4. The session is delivered to the user via the integrators app.

5. The user requests that the session is deleted via a mechanism within the integrator’s app, or the integrator app determines the session should be deleted.

6. The integrator app calls /api/delete_kasm. The return of /api/delete_kasm, does not guarantee that the session is fully deleted. The session may be deleted as part of a background task, or waiting for a persistent profile to be synchronized.

7. The integrator app calls /api/get_kasm_status to confirm the session is deleted. While optional, this step should be considered required if the session utilizes persistent profiles.

Request Kasm

Request for a new Kasm session to be created. Integrators should submit follow up requests to :ref:get-kasm-status to ensure the session reaches a running state, prior to directing the user to the session.

Permission Required: Users Auth Session and User

Note

If you intend to integrate Kasm into your app and will utilize iframes to load user sessions, be sure to set the Same Site Cookie Policy Global Setting to None if the Kasm Workspaces server is hosted under a different domain name. Reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite

POST /api/public/request_kasm

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "user_id": "8affcdbc16fc4910acb8a6dc268cd7ed",
    "image_id": "6a2d63fa8959412ca5fddd3890fb7223",
    "enable_sharing": true,
    "environment": { "ENV_VAR": "value" }
}

Example response:

{
    "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"
}

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.

kasm_url* string:

If specified, the browser inside the Kasm session will navigate to this page. This is only applicable if the Image used is Kasm Chrome, Kasm Firefox, or Kasm Tor Browser.

environment* dict:

Optional environmental variables to inject into the created container.

connection_info* dict:

Optional connection_info for specifying custom RDP/VNC/SSH connection settings. Not applicable to container based sessions.

* Optional

client_language* string:

Optional language string to be passed as an environment variable to the Kasm session. See Valid Languages for valid values.

client_timezone* string:

Optional timezone string to be passed as an environment variable to the Kasm session. See Valid Timezones for valid values.

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. Users should not be directed into Kasm sessions unless the status is Running. Followup calls to the Get Kasm Status endpoint may be called to verify the sessions current status.

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 Workspaces server address. It is in the form of /#/connect/kasm/<kasm_id>/<user_id>/<session_token>

Direct the user’s browser to this url to access the Kasm session. This link should not be re-used for different users.

Note

See this how-to guide for an example JSON that defines custom connection_info.

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. Integrators should wait until the sessions reaches a running operational_status prior to directing the end user into the session via kasm.operational_status. If the session is not in a running state, the kasm object may not be provided, in which case the caller should interrogate the top level operational_status. operational_progress and operational_message may be used to provide context to the user.

Permission Required: Users Auth Session and User

POST /api/public/get_kasm_status

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "user_id": "c7357f11eb4d47ad8021b5847d8415d8",
    "kasm_id": "d79ccb22-f6e7-4473-b8a2-a77da82278da"
}

Example response - Starting:

{
    "error_message": "This session is currently starting.",
    "operational_message": "Loading User Profile",
    "operational_progress": 50,
    "operational_status": "starting"
}

Example response - Running:

{
    "current_time": "2020-11-12 13:30:24.833834",
    "kasm_url": "/#/connect/kasm/116f18170fdc4a1a87146164a880fb93/583035bb-5819-4e51-83b9-21223badc569/2d110a49-4c6a-48b9-8cfb-398d6f543d5b",
    "kasm": {
        "expiration_date": "2020-11-12 14:28:40.446756",
        "container_ip": "192.168.32.9",
        "start_date": "2020-11-12 13:28:40.446737",
        "point_of_presence": null,
        "token": "43ab8a765e1e42fe9ee637783731f577",
        "image_id": "e12266d0f5f44bf5afb80b6c41fabce2",
        "view_only_token": "6f756f76e8704772bd8e32eb4d7bb835",
        "cores": 1.0,
        "hostname": "kasm.server",
        "kasm_id": "116f18170fdc4a1a87146164a880fb93",
        "port_map": {
            "audio": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/audio"
            },
            "vnc": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/vnc"
            },
            "audio_input": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/audio_input"
            },
            "uploads": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/uploads"
            }
        },
        "image": {
            "image_id": "e12266d0f5f44bf5afb80b6c41fabce2",
            "name": "kasmweb/chrome:1.8.0",
            "image_src": "img/thumbnails/chrome.png",
            "friendly_name": "Kasm Chrome"
        },
        "is_persistent_profile": false,
        "memory": 1768000000,
        "operational_status": "running",
        "client_settings": {
            "allow_kasm_audio": false,
            "idle_disconnect": 20,
            "lock_sharing_video_mode": true,
            "allow_persistent_profile": false,
            "allow_kasm_clipboard_down": false,
            "allow_kasm_microphone": false,
            "allow_kasm_downloads": false,
            "kasm_audio_default_on": false,
            "allow_point_of_presence": false,
            "allow_kasm_uploads": false,
            "allow_kasm_clipboard_up": false,
            "enable_webp": false,
            "allow_kasm_sharing": true,
            "allow_kasm_clipboard_seamless": false
        },
        "container_id": "dbc977159f79e55c466fec52a5b4954b7c26ba88e51937d85a5077d7c79e92e5",
        "port": 443,
        "keepalive_date": "2020-11-12 13:28:40.446754",
        "user_id": "583035bb58194e5183b921223badc569",
        "persistent_profile_mode": null,
        "share_id": "30a09d61",
        "host": "192.168.32.8",
        "server_id": "8270f8f0acfd4a34a56cc9a9cb7a67d9"
    }
}

Arguments

user_id string:

The user ID associated with the requested kasm.

kasm_id string:

The ID of the desired Kasm.

skip_agent_check bool

Skip connecting out to the agent to verify status of the container, instead use the current value in the database for the status.

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 Workspaces server address. It is in the form of /#/connect/kasm/<kasm_id>/<user_id>/<session_token>

Direct the user’s browser to this url to access the Kasm session. This link should not be re-used for different users.

operational_message string:

Provided if the session is not in a running state. May include a short description of the status of the request such as. “Loading User Profile”

operational_progress number:

Provided if the session is not in a running state. A number between 0 and 100 representing the precentage complete of the request.

operational_status string:

Provided if the session is not in a running state. The current status of the session.

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.

Permission Required: Users Auth Session and User

POST /api/public/join_kasm

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "user_id":"c7357f11eb4d47ad8021b5847d8415d8",
    "share_id":"89cc8cd3"
}

Example response:

{
    "current_time": "2020-11-12 13:36:16.065711",
    "session_token": "c9ade890-7693-44bc-a1d4-797bbddf6771",
    "user_id": "583035bb58194e5183b921223badc569",
    "kasm": {
        "port_map": {
            "vnc": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/vnc"
            },
            "audio": {
                "port": 443,
                "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/audio"
            }
        },
        "port": 443,
        "hostname": "kasm.server",
        "image": {
            "image_id": "e12266d0f5f44bf5afb80b6c41fabce2",
            "name": "kasmweb/chrome:1.8.0",
            "image_src": "img/thumbnails/chrome.png",
            "friendly_name": "Kasm Chrome"
        },
        "view_only_token": "6f756f76e8704772bd8e32eb4d7bb835",
        "user": {
            "username": "anon_2wipg0symxwmm4i1"
        },
        "share_id": "30a09d61",
        "host": "192.168.32.8",
        "client_settings": {
            "allow_kasm_audio": false,
            "idle_disconnect": 20,
            "lock_sharing_video_mode": true,
            "allow_persistent_profile": false,
            "allow_kasm_clipboard_down": false,
            "allow_kasm_microphone": false,
            "allow_kasm_downloads": false,
            "kasm_audio_default_on": false,
            "allow_point_of_presence": false,
            "allow_kasm_uploads": false,
            "allow_kasm_clipboard_up": false,
            "enable_webp": false,
            "allow_kasm_sharing": true,
            "allow_kasm_clipboard_seamless": false
        },
        "kasm_id": "116f18170fdc4a1a87146164a880fb93"
    },
    "username": "anon_2wipg0symxwmm4i1",
    "kasm_url": "/#/connect/join/30a09d61/583035bb58194e5183b921223badc569/c9ade890-7693-44bc-a1d4-797bbddf6771"
}

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/<share_id>/<user_id>/<session_token>

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.

Get Kasms

Retrieve a list of live sessions.

Permission Required: Sessions View

POST /api/public/get_kasms

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
}

Example response:

{
    "current_time": "2020-11-12 13:45:33.253299",
    "kasms": [
        {
            "expiration_date": "2020-11-12 14:28:40.446756",
            "container_ip": "192.168.32.9",
            "server": {
                "port": 443,
                "hostname": "proxy",
                "zone_name": "default",
                "provider": "hardware"
            },
            "user": {
                "username": "anon_2wipg0symxwmm4i1"
            },
            "start_date": "2020-11-12 13:28:40.446737",
            "point_of_presence": null,
            "token": "43ab8a765e1e42fe9ee637783731f577",
            "image_id": "e12266d0f5f44bf5afb80b6c41fabce2",
            "view_only_token": "6f756f76e8704772bd8e32eb4d7bb835",
            "cores": 1.0,
            "hostname": "proxy",
            "kasm_id": "116f18170fdc4a1a87146164a880fb93",
            "port_map": {
                "audio": {
                    "port": 443,
                    "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/audio"
                },
                "vnc": {
                    "port": 443,
                    "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/vnc"
                },
                "audio_input": {
                    "port": 443,
                    "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/audio_input"
                },
                "uploads": {
                    "port": 443,
                    "path": "desktop/116f1817-0fdc-4a1a-8714-6164a880fb93/uploads"
                }
            },
            "image": {
                "image_id": "e12266d0f5f44bf5afb80b6c41fabce2",
                "name": "kasmweb/chrome:1.8.0",
                "image_src": "img/thumbnails/chrome.png",
                "friendly_name": "Kasm Chrome"
            },
            "is_persistent_profile": false,
            "memory": 1768000000,
            "operational_status": "running",
            "client_settings": {
                "allow_kasm_audio": false,
                "idle_disconnect": 20,
                "lock_sharing_video_mode": true,
                "allow_persistent_profile": false,
                "allow_kasm_clipboard_down": false,
                "allow_kasm_microphone": false,
                "allow_kasm_downloads": false,
                "kasm_audio_default_on": false,
                "allow_point_of_presence": false,
                "allow_kasm_uploads": false,
                "allow_kasm_clipboard_up": false,
                "enable_webp": false,
                "allow_kasm_sharing": true,
                "allow_kasm_clipboard_seamless": false
            },
            "container_id": "dbc977159f79e55c466fec52a5b4954b7c26ba88e51937d85a5077d7c79e92e5",
            "port": 443,
            "keepalive_date": "2020-11-12 13:28:40.446754",
            "user_id": "583035bb58194e5183b921223badc569",
            "persistent_profile_mode": null,
            "share_id": "30a09d61",
            "host": "192.168.32.8",
            "server_id": "8270f8f0acfd4a34a56cc9a9cb7a67d9"
        }
    ]
}

Destroy Kasm

Destroy a Kasm session. The backend system my destroy the session immediately or queue the task for further processing prior to deletion such as saving off persistent profiles. If integrators wish to confirm the session is fully deleted, follow-up calls to :ref:get-kasm-status may be called, to confirm the session no longer exists. An error will be thrown

Permission Required: Users Auth Session and User

{
    "error_message": "Invalid kasm_id (7540775ad7d54634b8e7f5ec38b6373a)"
}

POST /api/public/destroy_kasm

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8",
    "user_id": "4d892bf39321494da9a159178972c147",

}

Example response:

{}

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 request was processed correctly.

Keepalive

Issue a keepalive to reset the expiration time of a Kasm session. The new expiration time will be updated to reflect the keepalive_expiration Group Setting assigned to the Kasm’s associated user.

Permission Required: Users Auth Session and User

POST /api/public/keepalive

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8"
}

Example response:

{
    "usage_reached": false
}

Arguments

kasm_id string:

The ID of the kasm to issue the expiration update.

Response Format

The response returns a single value usage_reached. If true, the user has exceeded the quota defined be the usage_limit group setting and the expiration time was not reset.

Frame Stats

Gets timing statistics for the next processed frame for a Kasm session. A user must be logged in and using a session for this API call to work. The stats include detailed timing stats on the processing of a single frame. Stats include frame analysis, jpeg/webp encoding, time in flight to client, and more.

Permission Required: Users Auth Session and User

POST /api/public/get_kasm_frame_stats

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8",
    "user_id": "4035b5e67750416cb8d6db14573ea38c",
    "client": "auto"
}

Example response:

{
    "frame":
    {
        "resx": 1512,
        "resy": 858,
        "changed": 10,
        "server_time": 12},
        "clients":
            [
                {
                    "client": "172.18.0.8_1635856777.276370::websocket",
                    "client_time": 0,
                    "ping": 27,
                    "processes": [{"process_name": "scanRenderQ", "time": 0}]
                }
            ],
        "analysis": 2,
        "screenshot": 2,
        "encoding_total": 2,
        "videoscaling": 0,
        "tightjpegencoder": {"time": 0, "count": 5, "area": 23005},
        "tightwebpencoder": {"time": 0, "count": 0, "area": 0}
    }

Arguments

kasm_id string:

The ID of the kasm to get the stats for

user_id string:

The ID of the user the session belongs to

client* string:

Which client to retrieve stats for: none, auto, all, or <user_websocket_id>. auto is the default and this will automatically select the client side stats for only the owner of the Kasm session. Use none for Server side stats only. Use all to get stats for all websocket clients. Use a KasmVNC websocket id, such as 172.18.0.8_1627985086.157123::websocket, to specify a specific client.

* Optional

Response Format

resx integer:

Resolution of frame on x axis.

resy integer:

Resolutino of frame on y axis.

changed integer:

Percentage of frame that had changes from last frame.

server_time integer:

Wall clock time to process frame in ms. Many processes are multi-threaded, this stat shows what the actual time was to fully process the frame serverside.

analysis integer:

Time taken, in ms, to perform pre-processing of the frame to determine changes.

encoding_total integer:

Time taken, in ms, to perform encoding. A frame is broken down into rects and based on processing power the rects are encoded in a mix of jpeg and webp and multiple threads. This time indicates the total wall clock time taken to perform encoding.

videoscaling integer:

When in video mode this represents the time taken, in ms, to perform scaling of the frame.

tightjpegencoder integer:

Total time, in ms, taken to processes all jpeg rects. Processing occurs in parrallel and this is the aggregate runtime of all threads and is thus not wall clock time.

tightwebpencoder integer:

Total time, in ms, taken to process all webp rects. Processing occurs in parrallel and this is the aggregate runtime of all threads and is thus not wall clock time.

clients array:

Array of client side stats for each connected client. At this time, ping is the only relevant stat. Ping is the amount of round trip time it takes for comms to the client, divide by two to get one way trip time.

Bottleneck Stats

Returns CPU and network bottleneck statistics that are relevant to the Kasm rendering process, KasmVNC. These metrics may be used to determine if rendering performance issues are CPU constraints on the server-side KasmVNC process or network bandwidth constraints. Stats are returned for each connected client. Since Kasm supports sharing sessions, there can be multiple clients connected to a single session.

Permission Required: Users Auth Session and User

POST /api/public/get_kasm_bottleneck_stats

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8",
    "user_id": "4035b5e67750416cb8d6db14573ea38c"
}

Example response:

{
    "kasm_user":
    {
        "172.18.0.8_1635858087.783615::websocket":
        [
            9.8,
            9.8,
            9.7,
            9.7
        ]
    }
}

Arguments

kasm_id string:

The ID of the kasm to issue the expiration update.

user_id string:

The ID of the user that owns the session.

Response Format

The response is JSON data containing an array of kasm user sessions. Each session has a dictionary entry with the key being the KasmVNC identifier for that websocket connection. The value is an array of decimal values ranging from 0 to 10. They represent, in order: CPU, CPU average, network, and network average. The lower the number, the moreconstrained KasmVNC is in being able to keep up with the target framerate.

Screenshot

Gets a screenshot of the requested session.

Permission Required: Users Auth Session and User

POST /api/public/get_kasm_screenshot

Example request:

JSONBash

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8",
    "user_id": "4035b5e67750416cb8d6db14573ea38c",
    "width": 300,
    "height": 300
}

Arguments

kasm_id string:

The ID of the kasm to issue the expiration update.

user_id string:

The ID of the user the session belongs to.

width* integer:

The width of the image. Default is 300.

height* integer:

The height of the image. Height is automatically overriden because the apsect ratio is kept and the height is adjusted accordingly.

* Optional

Response Format

The response is a JPEG image.

Exec Command

Execute an arbitrary command inside of a user’s session.

Permission Required: Sessions Modify

POST /api/public/exec_command_kasm

Example request:

JSONBash

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "kasm_id": "1a85859d-9d75-45e1-a173-e720472a24f8",
    "user_id": "4035b5e67750416cb8d6db14573ea38c",
    "exec_config":
    {
        "cmd": "xterm -c 'echo hello'",
        "environment":
        {
            "SOME_ENV_VAR": "some value"
        },
        "workdir": "/home/kasm-user",
        "privileged": false,
        "user": "root"
    }
}

Arguments

kasm_id string:

The ID of the kasm to issue the expiration update.

user_id string:

The ID of the user the session belongs to.

exec_config dict:

Dictionary of execution settings and the command to run.

exec_config.cmd string:

The command to run within the user’s container.

exec_config.environment* dict:

Environmental variables to be added to the environment for this exec session.

exec_config.workdir* string:

Path to working directory for this exec session.

exec_config.privileged* bool:

Run exec session as privileged.

exec_config.user* string:

The user to run the command as. By default it runs as the sandboxed normal user account. Specifying ‘root’ as the value will run the command as root inside the container and bypass the sandboxing that Kasm puts in place. The user value should be either root or not specified so that it runs as the sandboxed user, any other setting will result in the command failing.

* Optional

Response Format

kasm dict:

A dictionary containing details about the container that the command was executed on.

current_time timestamp:

The date and time the command was executed, in UTC.

Session Component Control

The developer may choose to hide the display of certain visual components that normally appear during a Kasm session. This is done by appending the following query arguments to any of the kasm_url response urls generated by the apis above.

Example

/#/connect/join/89cc8cd3/c7357f11eb4d47ad8021b5847d8415d8/070fce1f-86c6-4e05-9b10-935632acb8ce?disable_control_panel=1&disable_tips=1&disable_chat=1&disable_fixed_res=1

Query Arguments

disable_control_panel=1

Hides the Kasm control panel that is normally used for uploads, downloads etc. Users will be unable to access this functionality.

disable_tips=1

Stops the tips modal from showing when the user connects to a session.

disable_chat=1

Hides the chat interface for shared sessions.

disable_fixed_res=1

By default, shared sessions are forced into a fixed resolution and aspect ratio. When specified this will allow the shared session to operate with a dynamic resolution and aspect ratio.

Images

Get Images

Retrieve a list of available images.

Permission Required: Images View

POST /api/public/get_images

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
}

Example response:

{
    "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,
            "cpu_allocation_method": "Inherit",
            "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:1.8.0",
            "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 Session Recordings

Retrieve data for all of a specific session’s recordings. optionally get preauthorized download links for the clips from S3 compatible storage

Permission Required: Session Recordings View

POST /api/public/get_session_recordings

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_kasm_id": "10307f51-fd27-49f3-a84a-7aaa2f81d26e",
    "preauth_download_link": true
}

Example response:

{
"session_recordings":
    [
        {
            "recording_id": "c6113d5d419948e4910ec3cac91ea480",
            "account_id": "267e50ef66c94f88bfd1c39c413bc4d1",
            "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066120.mp4",
            "session_recording_metadata": {
                "duration": 63,
                "thumbnail": "<image data>",
                "timestamp": 1702065982
            },
            "session_recording_download_url": "<authenticated download URL>"
        },
        {
            "recording_id": "ebfd13f2dafc45fd956e8e574430f08e",
            "account_id": "267e50ef66c94f88bfd1c39c413bc4d1",
            "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066225.mp4",
            "session_recording_metadata": {
                "duration": 52,
                "thumbnail": "<image data>",
                "timestamp": 1702066047
            },
            "session_recording_download_url": "<authenticated downlaod URL>"
        }
    ]
}

Arguments

target_kasm_id string:

The ID of the kasm to get the recordings for

* Optional

preauth_download_link bool:

whether or not to generate preauth download links for the recording clips. Defaults to False

Response Format

session_recordings array:

List of all session recordings for the specified kasm ID

Get Sessions Recordings

Retrieve data for all recordings for a list of sessions. Optionally get preauthorized download links for the clips from S3 compatible storage

Permission Required: Session Recordings View

POST /api/public/get_sessions_recordings

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_kasm_ids": ["10307f51-fd27-49f3-a84a-7aaa2f81d26e","d7f6c231-aded-4747-9fb4-742f5182ed5d"],
    "preauth_download_link": true
}

Example response:

{
    "kasm_sessions": {
        "d7f6c231-aded-4747-9fb4-742f5182ed5d": {
            "session_recordings":
            [
                {
                    "recording_id": "dd1492515f2c4af8bcea184b3eb25f9c",
                    "account_id": "68c7e26ebdc34818a30198ada507dc7a",
                    "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-07/d7f6c231-aded-4747-9fb4-742f5182ed5d.1701980442.mp4",
                    "session_recording_metadata": {
                        "duration": 79,
                        "thumbnail": "<image data>",
                        "timestamp": 1701979849
                    },
                    "session_recording_download_url": "<authenticated download URL>"
                },
                {
                    "recording_id": "c886da0df36749308cc7b57c5668a8dd",
                    "account_id": "68c7e26ebdc34818a30198ada507dc7a",
                    "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-07/d7f6c231-aded-4747-9fb4-742f5182ed5d.1701980443.mp4",
                    "session_recording_metadata": {
                        "duration": 80,
                        "thumbnail": "<image data>",
                        "timestamp": 1701979930
                    },
                    "session_recording_download_url": "<authenticated downloaad URL>"
                },
                {
                    "recording_id": "cef476ec8ec7473e9b5b7a3ed2e245db",
                    "account_id": "68c7e26ebdc34818a30198ada507dc7a",
                    "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-07/d7f6c231-aded-4747-9fb4-742f5182ed5d.1701980444.mp4",
                    "session_recording_metadata": {
                        "duration": 36,
                        "thumbnail": "image data",
                        "timestamp": 1701980011
                    },
                    "session_recording_download_url": "<authenticated download URL>"
                }
            ]
        },
        "10307f51-fd27-49f3-a84a-7aaa2f81d26e": {
            "session_recordings":
            [
                {
                    "recording_id": "c6113d5d419948e4910ec3cac91ea480",
                    "account_id": "267e50ef66c94f88bfd1c39c413bc4d1",
                    "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066120.mp4",
                    "session_recording_metadata": {
                        "duration": 63,
                        "thumbnail": "<image data>",
                        "timestamp": 1702065982
                    },
                    "session_recording_download_url": "<authenticated download URL>"
                },
                {
                    "recording_id": "ebfd13f2dafc45fd956e8e574430f08e",
                    "account_id": "267e50ef66c94f88bfd1c39c413bc4d1",
                    "session_recording_url": "s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066225.mp4",
                    "session_recording_metadata": {
                        "duration": 52,
                        "thumbnail": "<image data>",
                        "timestamp": 1702066047
                    },
                    "session_recording_download_url": "<authenticated downlaod URL>"
                }
            ]
        }
    }
}

Arguments

target_kasm_ids array:

List of IDs of the kasms to get the recordings for

* Optional

preauth_download_link bool:

whether or not to generate preauth download links for the recording clips. Defaults to False

Response Format

session_recordings dict:

dictionary of all sessions recordings for the specified kasm IDs

Groups

Add User to Group

Add a user to an existing group.

Permission Required: Groups Modify, Groups Modify System to add the user to the built-in All Users or Administrator groups.

POST /api/public/add_user_group

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0"
    },
    "target_group": {
        "group_id": "87fd617577984033be5bd269b4d170c6"
    }
}

Example response:

{}

Remove User from Group

Remove a user from an existing group.

Permission Required: Groups Modify, Groups Modify System to remove a user from a built-in group All Users or Administrators.

POST /api/public/remove_user_group

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0"
    },
    "target_group": {
        "group_id": "87fd617577984033be5bd269b4d170c6"
    }
}

Example response:

{}

Login

Get Login

Generate a link for the user to login to Kasm without the need to enter a username or password. Redirect the user to the provided url.

Permission Required: Users Auth Session

POST /api/public/get_login

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0"
    }
}

Example response:

{
    "url": "https://kasm.server/#/connect/login/dash/57e8fc1afa864ff4947460d9831f42d5/930d6a5d-082e-438a-b5cf-98ae7ca5b67c"
}

Licensing

Activate

License the deployment by submitting an activation key. If valid, the returned license key will automatically be applied to the deployment.

Permission Required: Licenses Create

POST /api/public/activate

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "activation_key": "-----BEGIN ACTIVATION KEY-----eyJ0eXAiOiJ...-----END ACTIVATION KEY-----",
    "seats" : 10,
    "issued_to": "ACME Corp"
}

Example response:

{
    "license": {
        "license_id": "12e887e9e94a4615849f7963e9c85363",
        "expiration": "2022-11-06 18:07:08",
        "issued_at": "2021-11-05 18:07:08",
        "issued_to": "ACME Corp",
        "limit": 10,
        "is_verified": true,
        "license_type": "Per Concurrent Kasm",
        "features": {
            "auto_scaling": true,
            "branding": true,
            "session_staging": true,
            "session_casting": true,
            "log_forwarding": true,
            "developer_api": true,
            "inject_ssh_keys": true,
            "saml": true,
            "ldap": true,
            "session_sharing": true,
            "login_banner": true,
            "url_categorization": true,
            "usage_limit": true
        },
        "sku": "Enterprise"
    }
}

Arguments

activation_key string:

The activation key provide by Kasm Technologies.

seats* integer:

The desired number of seats to license the deployment for. If omitted the deployment will be licensed using the maximum number of seats as dictated by the entitlement.

issued_to* string:

A string representing the organization the deployment is licensed for.

* Optional

Response Format

license json object:

The detailed information about the license generated.

Session Staging

Get Staging Configs

Get a list of Staging Configs.

Permission Required: Staging View

POST /api/public/get_staging_configs

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
}

Example response:

{
    "staging_configs": [
        {
            "staging_config_id": "73f18b8826b74fb29a1066fb394878bc",
            "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
            "zone_name": "default",
            "image_id": "77b244ea4586469abde4feade309c377",
            "image_friendly_name": "Chrome",
            "num_sessions": 2,
            "num_current_sessions": 0,
            "expiration": 1,
            "allow_kasm_audio": true,
            "allow_kasm_uploads": false,
            "allow_kasm_downloads": true,
            "allow_kasm_clipboard_down": true,
            "allow_kasm_clipboard_up": true,
            "allow_kasm_microphone": true
        }
    ]
}

Response Format

staging_configs json object:

A list of Staging Configs.

Get Staging Config

Get an existing Staging Config.

Permission Required: Staging View

POST /api/public/get_staging_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_staging_config": {
        "staging_config_id": "ac3f18aa42ca4365874e51ab24f893c6"
    }
}

Example response:

{
    "staging_config": {
        "staging_config_id": "ac3f18aa42ca4365874e51ab24f893c6",
        "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
        "zone_name": "default",
        "image_id": "23b8330701e8492d985c25b2736ab522",
        "image_friendly_name": "Kali Linux",
        "num_sessions": 1,
        "num_current_sessions": 0,
        "expiration": 1.0,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": true,
        "allow_kasm_downloads": true,
        "allow_kasm_clipboard_down": true,
        "allow_kasm_clipboard_up": true,
        "allow_kasm_microphone": true
    }
}

Arguments

target_staging_config.staging_config_id string:

The ID of the staging config to be updated.

Response Format

staging_config json object:

The requested staging config.

Create Staging Config

Create a new Staging Config.

Permission Required: Staging Create

POST /api/public/create_staging_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_staging_config": {
        "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
        "image_id": "23b8330701e8492d985c25b2736ab522",
        "num_sessions": 1,
        "expiration": 1,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": true,
        "allow_kasm_downloads": true,
        "allow_kasm_clipboard_down": true,
        "allow_kasm_clipboard_up": true,
        "allow_kasm_microphone": true
    }
}

Example response:

{
    "staging_config": {
        "staging_config_id": "ac3f18aa42ca4365874e51ab24f893c6",
        "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
        "zone_name": "default",
        "image_id": "23b8330701e8492d985c25b2736ab522",
        "image_friendly_name": "Kali Linux",
        "num_sessions": 1,
        "num_current_sessions": 0,
        "expiration": 1,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": true,
        "allow_kasm_downloads": true,
        "allow_kasm_clipboard_down": true,
        "allow_kasm_clipboard_up": true,
        "allow_kasm_microphone": true
    }
}

Arguments

target_staging_config.zone_id string:

The Zone Id for the staging config.

target_staging_config.image_id string:

The Image Id to use for the staging config.

target_staging_config.num_sessions integer

The number of sessions the system will attempt to have staged at any given time.

target_staging_config.expiration integer

Staged sessions that have not been assigned to a user will expire after this amount of time (in hours). The system will destroy the staged sessions and re-created them.

target_staging_config.allow_kasm_audio bool

When enabled, the staged session will support streaming audio from the session to the user.

target_staging_config.allow_kasm_uploads bool

When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel.

target_staging_config.allow_kasm_downloads bool

When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget.

target_staging_config.allow_kasm_clipboard_down bool

When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard.

target_staging_config.allow_kasm_clipboard_up bool

When enabled, the staged session will allow copying data from the user’s local computer to the session.

target_staging_config.allow_kasm_microphone bool

When enabled, the staged session will allow the user to pass their local microphone into the session.

Response Format

staging_config json object:

The created staging config.

Update Staging Config

Get a list of Staging Configs.

Permission Required: Staging Modify

POST /api/public/update_staging_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_staging_config": {
        "staging_config_id": "73f18b8826b74fb29a1066fb394878bc",
        "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
        "image_id": "77b244ea4586469abde4feade309c377",
        "num_sessions": 2,
        "expiration": 2,
        "allow_kasm_audio": false,
        "allow_kasm_uploads": false,
        "allow_kasm_downloads": false,
        "allow_kasm_clipboard_down": false,
        "allow_kasm_clipboard_up": false,
        "allow_kasm_microphone": false
    }
}

Example response:

{
    "staging_config": {
        "staging_config_id": "73f18b8826b74fb29a1066fb394878bc",
        "zone_id": "e35b0ebd444d4120ad6d4f3db221003d",
        "zone_name": "default",
        "image_id": "77b244ea4586469abde4feade309c377",
        "image_friendly_name": "Chrome",
        "num_sessions": 2,
        "num_current_sessions": 0,
        "expiration": 2,
        "allow_kasm_audio": false,
        "allow_kasm_uploads": false,
        "allow_kasm_downloads": false,
        "allow_kasm_clipboard_down": false,
        "allow_kasm_clipboard_up": false,
        "allow_kasm_microphone": false
    }
}

Arguments

target_staging_config.staging_config_id string:

The ID of the staging config to be updated.

target_staging_config.zone_id* string:

The Zone Id for the staging config.

target_staging_config.image_id* string:

The Image Id to use for the staging config.

target_staging_config.num_sessions* integer

The number of sessions the system will attempt to have staged at any given time.

target_staging_config.expiration* integer

Staged sessions that have not been assigned to a user will expire after this amount of time (in hours). The system will destroy the staged sessions and re-created them.

target_staging_config.allow_kasm_audio* bool

When enabled, the staged session will support streaming audio from the session to the user.

target_staging_config.allow_kasm_uploads* bool

When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel.

target_staging_config.allow_kasm_downloads* bool

When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget.

target_staging_config.allow_kasm_clipboard_down* bool

When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard.

target_staging_config.allow_kasm_clipboard_up* bool

When enabled, the staged session will allow copying data from the user’s local computer to the session.

target_staging_config.allow_kasm_microphone* bool

When enabled, the staged session will allow the user to pass their local microphone into the session.

* Optional

Response Format

staging_config json object:

The updated staging config.

Delete Staging Config

Delete an existing Staging Config.

Permission Required: Staging Delete

POST /api/public/delete_staging_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_staging_config": {
        "staging_config_id": "ac3f18aa42ca4365874e51ab24f893c6"
    }
}

Example response:

{}

Arguments

target_staging_config.staging_config_id string:

The ID of the staging config to be updated.

Response Format

If empty, the delete request was successful

Deployment Zones

Get Zones

Get a list of Deployment Zones.

Permission Required: Zones View

POST /api/public/get_zones

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "brief" : true
}

Example response (Truncated for brevity):

{
  "zones": [
        {
          "zone_id": "556641990fbd433197b9e8f0d1e0404a",
          "zone_name": "default",
          "auto_scaling_enabled": false,
          "aws_enabled": false,
          "aws_region": "us-east-1",
          "aws_access_key_id": "changeme",
          "aws_secret_access_key": "**********",
          "ec2_agent_ami_id": "changeme"
        }
    ]
}

Arguments

brief* bool:

Limit the information returned for each zone.

* Optional

Response Format

zones json object:

A list of Deployment Zones.

Session Tokens

Session tokens authenticate user’s requests to access functionality within the system.

Attributes

• session_token

  • This is the value of the token: (UUID)

• session_date

  • The time the token was created or last promoted (DateTime)

• expires_at

  • The time the token will no longer be valid. This is session_date + the global setting “Session Lifetime” (DateTime)

Create Session Token

Create a session token for a user.

Permission Required: Users Auth Session

POST /api/public/create_session_token

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "009c3779-4fa0-4af8-9722-8daf195718c0"
     }
 }

Example response:

{
    "session_token": {
        "session_token": "c324f7296dd3406594a261b411c862bb",
        "session_token_date": "2021-12-22 08:05:44.508675",
        "expires_at": "2021-12-23 08:05:44.508675"
    }
}

Get Session Token

Query the information about a specific session token.

Permission Required: Users Auth Session

POST /api/public/get_session_token

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_token": {
         "session_token": "b8885ffe108f491dbb66be31bceb34c2"
     }
 }

Example response:

{
    "session_token": {
        "session_token": "b8885ffe108f491dbb66be31bceb34c2",
        "session_token_date": "2021-12-22 08:00:24.033284",
        "expires_at": "2021-12-25 16:00:24.033284"
    }
}

Get Session Tokens

Get all session tokens for a user.

Permission Required: Users Auth Sessions

POST /api/public/get_session_tokens

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "009c3779-4fa0-4af8-9722-8daf195718c0"
     }
 }

Example response:

{
    "session_tokens": [
        {
            "session_token": "b8885ffe108f491dbb66be31bceb34c2",
            "session_token_date": "2021-12-22 07:50:11.047577",
            "expires_at": "2021-12-25 15:50:11.047577"
        },
        {
            "session_token": "01904563d58f43f2b6e8fdcc610728dc",
            "session_token_date": "2021-12-22 07:53:54.742402",
            "expires_at": "2021-12-25 15:53:54.742402"
        }
    ]
}

Update Session Token

Promote an existing session token.

Permission Required: Users Auth Sessions

POST /api/public/update_session_token

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_token": {
         "session_token": "b8885ffe108f491dbb66be31bceb34c2"
     }
 }

Example response:

{
    "session_token": {
        "session_token": "b8885ffe108f491dbb66be31bceb34c2",
        "session_token_date": "2021-12-22 08:11:52.913849",
        "expires_at": "2021-12-23 08:11:52.913849"
    }
}

Delete Session Token

Delete a single session token for the user.

Permission Required: User Auth Sessions

POST /api/public/delete_session_token

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_token": {
         "session_token": "b8885ffe108f491dbb66be31bceb34c2"
     }
 }

Example response:

{}

Delete Session Tokens

Delete all session tokens for a given user.

Permission Required: User Auth Sessions

POST /api/public/delete_session_tokens

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_user": {
         "user_id": "009c3779-4fa0-4af8-9722-8daf195718c0"
     }
 }

Example response:

{}

Shared Session Permissions

Developers may wish to have more than one user access a single session. In order to give secondary users access to a given session, the developer must explicitly give another user access via Session Permissions after placing the session in Sharing mode. Session Permissions only apply to non-owners of the Kasm session.

Attributes

• session_permissions_id

  • A unique identifier given to the session permission entry

• kasm_id

  • The Kasm session id for the permission

• user_id

  • The User Id for the permission

• vnc_username

  • The auto-generated vnc user that maps to the permission. This is exposed inside the session container.

• access

  • Access flags that determine the level of permissions. E.g "access": "r".

    • Freeze: "access": "". The users us able to connect but will not receive screen updates, nor be able to imput controls

    • Read: "access": "r" The user will receive screen updates but will not be able to control inputs

    • Read/Write "access": "rw" (implied read). The user will receive screen updates and control inputs

Set Session Permissions

Give a set of users access to a Kasm session.

Permission Required: Sessions Modify

POST /api/public/set_session_permissions

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_permissions": {
         "kasm_id": "e31320b3-4ef2-41dd-aa6e-f9e85270cd7e",
         "session_permissions": [
             {
                 "user_id": "2e559e29-9bf1-45a2-8c08-c30c7c253e42",
                 "access": "rw"
             },
             {
                 "user_id": "e64c996c-efc1-4754-8f71-816a78619f39",
                 "access": "r"
             },
             {
                 "user_id": "5edbadc6-886e-4ad8-9ff7-97f396a9d747",
                 "access": ""
             }
         ]
     }
 }

Example response:

{
    "session_permissions": [
        {
            "session_permission_id": "c391e4267e574b3d90731b2a843a2b98",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "2e559e299bf145a28c08c30c7c253e42",
            "access": "rw",
            "vnc_username": "e9d2682a5e824de",
            "username": "user@kasm.local"
        },
        {
            "session_permission_id": "62eb4ae2b0ec487db61e9dc36f47b342",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "e64c996cefc147548f71816a78619f39",
            "access": "r",
            "vnc_username": "49c073c7dd854ad",
            "username": "user2@kasm.local"
        },
        {
            "session_permission_id": "b0e9d7ab859648289f70395570734a3e",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "5edbadc6886e4ad89ff797f396a9d747",
            "access": "",
            "vnc_username": "b8f50c6ba1cf424",
            "username": "user3@kasm.local"
        }
    ]
}

Set All Session Permissions

Set the permissions for all participants for a given Kasm session.

Permission Required: Sessions Modify

POST /api/public/set_session_permissions

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_permissions": {
         "kasm_id": "e31320b3-4ef2-41dd-aa6e-f9e85270cd7e",
         "access": "r"
     }
 }

Example response:

{
    "session_permissions": [
        {
            "session_permission_id": "c391e4267e574b3d90731b2a843a2b98",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "2e559e299bf145a28c08c30c7c253e42",
            "access": "r",
            "vnc_username": "e9d2682a5e824de",
            "username": "user@kasm.local"
        },
        {
            "session_permission_id": "62eb4ae2b0ec487db61e9dc36f47b342",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "e64c996cefc147548f71816a78619f39",
            "access": "r",
            "vnc_username": "49c073c7dd854ad",
            "username": "user2@kasm.local"
        },
        {
            "session_permission_id": "b0e9d7ab859648289f70395570734a3e",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "5edbadc6886e4ad89ff797f396a9d747",
            "access": "r",
            "vnc_username": "b8f50c6ba1cf424",
            "username": "user3@kasm.local"
        }
    ]
}

Get Session Permissions

Get session permissions for a Kasm session and/or user Permission Required: Sessions Modify

POST /api/public/get_session_permissions

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_permissions" :{
         "kasm_id": "e31320b3-4ef2-41dd-aa6e-f9e85270cd7e",
         "user_id": "5edbadc6886e4ad89ff797f396a9d747"
     }
 }

Example response:

{
    "session_permissions": [
        {
            "session_permission_id": "b0e9d7ab859648289f70395570734a3e",
            "kasm_id": "e31320b34ef241ddaa6ef9e85270cd7e",
            "user_id": "5edbadc6886e4ad89ff797f396a9d747",
            "access": "",
            "vnc_username": "b8f50c6ba1cf424",
            "username": "user3@kasm.local"
        }
    ]
}

Delete Session Permissions

Remove session permissions for a given Kasm session.

Permission Required: Sessions Modify

POST /api/public/delete_session_permissions

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_permissions":{
         "kasm_id": "e31320b3-4ef2-41dd-aa6e-f9e85270cd7e",
         "user_ids": [
             "2e559e29-9bf1-45a2-8c08-c30c7c253e42",
             "e64c996c-efc1-4754-8f71-816a78619f39"
         ]
     }
 }

Example response:

{}

Delete All Session Permissions

Remove all participant session permissions for a given Kasm session.

Permission Required: Sessions Modify

POST /api/public/delete_all_session_permissions

Example request:

JSON

{
     "api_key": "{{api_key}}",
     "api_key_secret": "{{api_key_secret}}",
     "target_session_permissions":{
         "kasm_id": "e31320b3-4ef2-41dd-aa6e-f9e85270cd7e"
     }
 }

Example response:

{}

Session Casting

Get Cast Configs

Get a list of Casting Configs.

Permission Required: Casting View

POST /api/public/get_cast_configs

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
}

Example response:

{
    "cast_configs": [
        {
            "casting_config_name" : "Chrome Configuration",
            "cast_config_id": "e7fed0de23234a3084bffa3e8397759f",
            "image_id": "90c473864949488c902aa6e4adbf89a6",
            "image_friendly_name": "Chrome",
            "allowed_referrers": [
                "acme.com",
                "contoso.com"
            ],
            "limit_sessions": false,
            "session_remaining": 0,
            "limit_ips": false,
            "ip_request_limit": 0,
            "ip_request_seconds": 0,
            "error_url": null,
            "enable_sharing": false,
            "disable_control_panel": false,
            "disable_tips": false,
            "disable_fixed_res": false,
            "key": "abc123",
            "allow_anonymous": true,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "require_recaptcha": true,
            "group_name": "All Users",
            "kasm_url": "https://google.com",
            "dynamic_kasm_url": false,
            "dynamic_docker_network": false,
            "allow_resume": true,
            "enforce_client_settings": true,
            "allow_kasm_audio": true,
            "allow_kasm_uploads": false,
            "allow_kasm_downloads": false,
            "allow_kasm_clipboard_down": false,
            "allow_kasm_clipboard_up": false,
            "allow_kasm_microphone": false,
            "valid_until": "2022-06-20 10:00:00",
            "allow_kasm_sharing": false,
            "kasm_audio_default_on": true,
            "kasm_ime_mode_default_on": true
        }
    ]
}

Response Format

cast_configs json object:

A list of Casting Configs.

Get Cast Config

Get an existing Casting Config.

Permission Required: Casting View

POST /api/public/get_cast_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "cast_config_id": "ac3f18aa42ca4365874e51ab24f893c6"
}

Example response:

{
    "cast_config": {
        "casting_config_name": "Chrome Configuration",
        "cast_config_id": "e7fed0de23234a3084bffa3e8397759f",
        "image_id": "90c473864949488c902aa6e4adbf89a6",
        "image_friendly_name": "Chrome",
        "allowed_referrers": [
            "acme.com",
            "contoso.com"
        ],
        "limit_sessions": false,
        "session_remaining": 0,
        "limit_ips": false,
        "ip_request_limit": 0,
        "ip_request_seconds": 0,
        "error_url": null,
        "enable_sharing": false,
        "disable_control_panel": false,
        "disable_tips": false,
        "disable_fixed_res": false,
        "key": "abc123",
        "allow_anonymous": true,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "require_recaptcha": true,
        "group_name": "All Users",
        "kasm_url": "https://google.com",
        "dynamic_kasm_url": false,
        "dynamic_docker_network": false,
        "allow_resume": true,
        "enforce_client_settings": true,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": false,
        "allow_kasm_downloads": false,
        "allow_kasm_clipboard_down": false,
        "allow_kasm_clipboard_up": false,
        "allow_kasm_microphone": false,
        "valid_until": "2022-06-20 10:00:00",
        "allow_kasm_sharing": false,
        "kasm_audio_default_on": true,
        "kasm_ime_mode_default_on": true
    }
}

Arguments

cast_config_id string:

The ID of the casting config to be queried.

Response Format

cast_config json object:

The requested Casting config.

Create Cast Config

Create a Session Casting Config

Permission Required: Casting Create

POST /api/public/create_cast_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_cast_config":
        {
            "casting_config_name": "My New Configuration",
            "image_id": "5383dd0238a94554b4611d2a9f943cda",
            "allowed_referrers": [
                "example.com",
                "contoso.com"
            ],
            "limit_sessions": false,
            "session_remaining": 0,
            "limit_ips": false,
            "ip_request_limit": 0,
            "ip_request_seconds": 0,
            "error_url": null,
            "enable_sharing": false,
            "disable_control_panel": false,
            "disable_tips": false,
            "disable_fixed_res": false,
            "key": "123",
            "allow_anonymous": false,
            "group_id": null,
            "require_recaptcha": false,
            "kasm_url": null,
            "dynamic_kasm_url": false,
            "dynamic_docker_network": false,
            "allow_resume": true,
            "enforce_client_settings": true,
            "allow_kasm_audio": true,
            "allow_kasm_uploads": false,
            "allow_kasm_downloads": false,
            "allow_kasm_clipboard_down": false,
            "allow_kasm_clipboard_up": false,
            "allow_kasm_microphone": false,
            "valid_until": "2022-06-20 10:00:00",
            "allow_kasm_sharing": false,
            "kasm_audio_default_on": true,
            "kasm_ime_mode_default_on": true
        }
}

Example response:

{
    "cast_config": {
        "casting_config_name": "My New Configuration",
        "cast_config_id": "c423b160dc884000981da374842b0ef8",
        "image_id": "5383dd0238a94554b4611d2a9f943cda",
        "image_friendly_name": "Ubuntu Focal",
        "allowed_referrers": [
            "example.com",
            "contoso.com"
        ],
        "limit_sessions": false,
        "session_remaining": 0,
        "limit_ips": false,
        "ip_request_limit": 0,
        "ip_request_seconds": 0,
        "error_url": null,
        "enable_sharing": false,
        "disable_control_panel": false,
        "disable_tips": false,
        "disable_fixed_res": false,
        "key": "123",
        "allow_anonymous": false,
        "group_id": null,
        "require_recaptcha": false,
        "group_name": null,
        "kasm_url": null,
        "dynamic_kasm_url": false,
        "dynamic_docker_network": false,
        "allow_resume": true,
        "enforce_client_settings": true,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": false,
        "allow_kasm_downloads": false,
        "allow_kasm_clipboard_down": false,
        "allow_kasm_clipboard_up": false,
        "allow_kasm_microphone": false,
        "valid_until": "2022-06-20 10:00:00",
        "allow_kasm_sharing": false,
        "kasm_audio_default_on": true,
        "kasm_ime_mode_default_on": true
    }
}

Arguments

target_cast_config.casting_config_name string

The configuration name.

target_cast_config.image_id string:

The Image Id to use for the casting config.

target_cast_config.allowed_referrers* list:

A list of domains allowed as referrers when a casting link is visited.

target_cast_config.limit_sessions* bool:

When enabled, the total number of sessions for this config will be limited.

target_cast_config.session_remaining* integer

The number of sessions that are allowed to be spawned from this casting link.

target_cast_config.limit_ips* integer

When enabled, the system will limit the number of requests that will employ rate-limiting based on the source IP of the request. (e.g limiting requests to 1 sessions per 60 seconds)

target_cast_config.ip_request_limit* bool

When limit_ips is enabled, this value is used as the total number of sessions that are allowed for the given time period as defined in Within Seconds.

target_cast_config.ip_request_seconds* bool

When Llimit_ips is enabled, this value sets the timeframe (in seconds) that is used for the source IP.

target_cast_config.error_url* bool

If defined, the user will be pushed to this URL when an error (such as IP rate limit violation) occurs. If left blank, an internal error page is shown.

target_cast_config.enable_sharing* bool

When enabled, this session will automatically have sharing activated.

target_cast_config.disable_control_panel* bool

When enabled, the Control Panel widget is not shown for the sessions.

target_cast_config.disable_tips* bool

When enabled, the Tips dialogue is not shown when a user enters a session.

target_cast_config.disable_fixed_res* bool

When enabled and the session is in sharing mode, the resolution will be dynamic. The resolution is typically fixed when a session enters sharing mode.

target_cast_config.key* bool

The unique identifier for a Casting URL. If 123abc is the key, users will launch sessions via the following URL https://my.kasm.server/#/cast/123abc

target_cast_config.allow_anonymous* bool

If enabled, requests to the Casting URL will not require authentication. Instead the system will create an anonymous users account for each new request.

target_cast_config.group_id* bool

When Allow Anonymous is enabled, the system will create new user accounts for each new request. These anonymous users accounts will automatically be added to the All Users Group and an additional Group defined here. Administrators can configure the appropriate Group Settings to configure permissions such as allow_kasm_downloads etc on this Group.

target_cast_config.require_recaptcha* bool

When Allow Anonymous is enabled, administrators can choose to have requests validated by Google reCAPTCHA . To use this feature, the Google reCAPTCHA Private Key and Google reCAPTCHA Site Key properties must be set in the Server Settings.

target_cast_config.kasm_url* bool

If defined, this value will populate as the KASM_URL environment variable for created or assigned Staged Sessions. These values are often used in the Docker Exec Configs of the browser Images.

target_cast_config.dynamic_kasm_url* bool

When enabled, the user is allowed to append a kasm_url query argument to the cast url. e.g https://kasm.server/#/cast/123?kasm_url=example.com If present the system will use this value as the KASM_URL. When used in conjunction with Allow Resume, this will open a new tab with the specified KASM_URL when the session is resumed

target_cast_config.dynamic_docker_network* bool

When enabled, the user is allowed to append a docker_network query argument to the cast url. e.g https://kasm.server/#/cast/123?docker_network=example_network The Image used must have Allow Network Selection enabled.

target_cast_config.allow_resume* bool

When enabled, authenticated users who already have a running session will have their session resumed instead of having a new session created when connecting to the same Casting URL

target_cast_config.enforce_client_settings* bool

When enabled, the client settings listed below will be enforced on the session , overriding the client settings attached to the user’s group(s)

target_cast_config.allow_kasm_audio* bool

When enabled and, the staged session will support streaming audio from the session to the user. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_uploads* bool

When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_downloads* bool

When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_clipboard_down* bool

When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_clipboard_up* bool

When enabled, the staged session will allow copying data from the user’s local computer to the session. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_microphone* bool

When enabled, the staged session will allow the user to pass their local microphone into the session. Applicable if enforce_client_settings is enabled.

target_cast_config.valid_until* bool

When defined, the casting link will only be valid until this time, after which the client will be presented with an error. Defined in UTC.

target_cast_config.allow_kasm_sharing* bool

When enabled, the user will be able to place their session in sharing mode. Applicable if enforce_client_settings is enabled.

target_cast_config.kasm_audio_default_on* bool

When disabled, the audio service will be muted by default. Applicable if enforce_client_settings is enabled.

target_cast_config.kasm_ime_mode_default_on* bool

When enabled, IME mode will be enabled by default if the doesnt already have a local preference set. Applicable if enforce_client_settings is enabled.

* Optional

Response Format

cast_config json object:

The updated casting config.

Update Cast Config

Update a Session Casting Config

Permission Required: Casting Modify

POST /api/public/update_cast_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_cast_config":
        {
            "casting_config_name": "My New Configuration",
            "cast_config_id": "c423b160dc884000981da374842b0ef8",
            "image_id": "5383dd0238a94554b4611d2a9f943cda",
            "allowed_referrers": [
                "example.com",
                "contoso.com"
            ],
            "limit_sessions": false,
            "session_remaining": 0,
            "limit_ips": false,
            "ip_request_limit": 0,
            "ip_request_seconds": 0,
            "error_url": null,
            "enable_sharing": false,
            "disable_control_panel": false,
            "disable_tips": false,
            "disable_fixed_res": false,
            "key": "123",
            "allow_anonymous": false,
            "group_id": null,
            "require_recaptcha": false,
            "kasm_url": null,
            "dynamic_kasm_url": false,
            "dynamic_docker_network": false,
            "allow_resume": true,
            "enforce_client_settings": true,
            "allow_kasm_audio": true,
            "allow_kasm_uploads": false,
            "allow_kasm_downloads": false,
            "allow_kasm_clipboard_down": false,
            "allow_kasm_clipboard_up": false,
            "allow_kasm_microphone": false,
            "valid_until": "2022-06-20 10:00:00",
            "allow_kasm_sharing": false,
            "kasm_audio_default_on": true,
            "kasm_ime_mode_default_on": true
        }
}

Example response:

{
    "cast_config": {
        "casting_config_name": "My New Configuration",
        "cast_config_id": "c423b160dc884000981da374842b0ef8",
        "image_id": "5383dd0238a94554b4611d2a9f943cda",
        "image_friendly_name": "Ubuntu Focal",
        "allowed_referrers": [
            "example.com",
            "contoso.com"
        ],
        "limit_sessions": false,
        "session_remaining": 0,
        "limit_ips": false,
        "ip_request_limit": 0,
        "ip_request_seconds": 0,
        "error_url": null,
        "enable_sharing": false,
        "disable_control_panel": false,
        "disable_tips": false,
        "disable_fixed_res": false,
        "key": "123",
        "allow_anonymous": false,
        "group_id": null,
        "require_recaptcha": false,
        "group_name": null,
        "kasm_url": null,
        "dynamic_kasm_url": false,
        "dynamic_docker_network": false,
        "allow_resume": true,
        "enforce_client_settings": true,
        "allow_kasm_audio": true,
        "allow_kasm_uploads": false,
        "allow_kasm_downloads": false,
        "allow_kasm_clipboard_down": false,
        "allow_kasm_clipboard_up": false,
        "allow_kasm_microphone": false,
        "valid_until": "2022-06-20 10:00:00",
        "allow_kasm_sharing": false,
        "kasm_audio_default_on": true,
        "kasm_ime_mode_default_on": true
    }
}

Arguments

target_cast_config.cast_config_id string:

The ID of the desired casting config to update.

target_cast_config.image_id string:

The Image Id to use for the casting config.

target_cast_config.allowed_referrers* list:

A list of domains allowed as referrers when a casting link is visited.

target_cast_config.limit_sessions* bool:

When enabled, the total number of sessions for this config will be limited.

target_cast_config.session_remaining* integer

The number of sessions that are allowed to be spawned from this casting link.

target_cast_config.limit_ips* integer

When enabled, the system will limit the number of requests that will employ rate-limiting based on the source IP of the request. (e.g limiting requests to 1 sessions per 60 seconds)

target_cast_config.ip_request_limit* bool

When limit_ips is enabled, this value is used as the total number of sessions that are allowed for the given time period as defined in Within Seconds.

target_cast_config.ip_request_seconds* bool

When Llimit_ips is enabled, this value sets the timeframe (in seconds) that is used for the source IP.

target_cast_config.error_url* bool

If defined, the user will be pushed to this URL when an error (such as IP rate limit violation) occurs. If left blank, an internal error page is shown.

target_cast_config.enable_sharing* bool

When enabled, this session will automatically have sharing activated.

target_cast_config.disable_control_panel* bool

When enabled, the Control Panel widget is not shown for the sessions.

target_cast_config.disable_tips* bool

When enabled, the Tips dialogue is not shown when a user enters a session.

target_cast_config.disable_fixed_res* bool

When enabled and the session is in sharing mode, the resolution will be dynamic. The resolution is typically fixed when a session enters sharing mode.

target_cast_config.key* bool

The unique identifier for a Casting URL. If 123abc is the key, users will launch sessions via the following URL https://my.kasm.server/#/cast/123abc

target_cast_config.allow_anonymous* bool

If enabled, requests to the Casting URL will not require authentication. Instead the system will create an anonymous users account for each new request.

target_cast_config.group_id* bool

When Allow Anonymous is enabled, the system will create new user accounts for each new request. These anonymous users accounts will automatically be added to the All Users Group and an additional Group defined here. Administrators can configure the appropriate Group Settings to configure permissions such as allow_kasm_downloads etc on this Group.

target_cast_config.require_recaptcha* bool

When Allow Anonymous is enabled, administrators can choose to have requests validated by Google reCAPTCHA . To use this feature, the Google reCAPTCHA Private Key and Google reCAPTCHA Site Key properties must be set in the Server Settings.

target_cast_config.kasm_url* bool

If defined, this value will populate as the KASM_URL environment variable for created or assigned Staged Sessions. These values are often used in the Docker Exec Configs of the browser Images.

target_cast_config.dynamic_kasm_url* bool

When enabled, the user is allowed to append a kasm_url query argument to the cast url. e.g https://kasm.server/#/cast/123?kasm_url=example.com If present the system will use this value as the KASM_URL. When used in conjunction with Allow Resume, this will open a new tab with the specified KASM_URL when the session is resumed

target_cast_config.dynamic_docker_network* bool

When enabled, the user is allowed to append a docker_network query argument to the cast url. e.g https://kasm.server/#/cast/123?docker_network=example_network The Image used must have Allow Network Selection enabled.

target_cast_config.allow_resume* bool

When enabled, authenticated users who already have a running session will have their session resumed instead of having a new session created when connecting to the same Casting URL

target_cast_config.enforce_client_settings* bool

When enabled, the client settings listed below will be enforced on the session , overriding the client settings attached to the user’s group(s)

target_cast_config.allow_kasm_audio* bool

When enabled and, the staged session will support streaming audio from the session to the user. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_uploads* bool

When enabled, the staged session will allow the user to upload files from their local computer to the session via the upload widget in the control panel. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_downloads* bool

When enabled, the staged session will allow download files from the session to their local computer via the control panel download widget. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_clipboard_down* bool

When enabled, the staged session will allow copying data from the session to the users local computer via the clipboard. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_clipboard_up* bool

When enabled, the staged session will allow copying data from the user’s local computer to the session. Applicable if enforce_client_settings is enabled.

target_cast_config.allow_kasm_microphone* bool

When enabled, the created session will allow the user to pass their local microphone into the session. Applicable if enforce_client_settings is enabled.

target_cast_config.valid_until* bool

When defined, the casting link will only be valid until this time, after which the client will be presented with an error. Defined in UTC.

target_cast_config.allow_kasm_sharing* bool

When enabled, the user will be able to place their session in sharing mode. Applicable if enforce_client_settings is enabled.

target_cast_config.kasm_audio_default_on* bool

When disabled, the audio service will be muted by default. Applicable if enforce_client_settings is enabled.

target_cast_config.kasm_ime_mode_default_on* bool

When enabled, IME mode will be enabled by default if the doesnt already have a local preference set. Applicable if enforce_client_settings is enabled.

* Optional

Response Format

cast_config json object:

The updated casting config.

Delete Cast Config

Get an existing Casting Config.

Permission Required: Casting Delete

POST /api/public/delete_cast_config

Example request:

JSON

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "cast_config_id": "ac3f18aa42ca4365874e51ab24f893c6",
    "casting_config_name": "Chrome Configuration",
}

Example response:

{}

Arguments

cast_config_id string:

The ID of the casting config to be queried.

API Example

This is an example implementation of the Kasm Developer API using Python and Flask. The code can be downloaded from Bitbucket