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 Auth Captcha	Modify global settings in the authentication captcha 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.
Egress Providers View	View Egress Providers.
Egress Providers Modify	Modify existing Egress Providers.
Egress Providers Create	Create new Egress Providers.
Egress Providers Delete	Delete an existing Egress Provider.
Egress Gateways View	View Egress Gateways.
Egress Gateways Modify	Modify existing Egress Gateways.
Egress Gateways Create	Create new Egress Gateways.
Egress Gateways Delete	Delete an existing Egress Gateway.
Egress Credentials View	View Egress Credentials.
Egress Credentials Modify	Modify existing Egress Credentials.
Egress Credentials Create	Create new Egress Credentials.
Egress Credentials Delete	Delete an existing Egress Credential.
Banners View	View banners.
Banners Modify	Modify existing banners.
Banners Create	Create new banners.
Banners Delete	Delete an existing banner.
AD User Management View	View AD User Management Configurations.
AD User Management Modify	Modify existing AD User Management Configurations.
AD User Management Create	Create new AD User Management Configurations.
AD User Management Delete	Delete an existing AD User Management Configuration.

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
• Egress Gateways Create, Egress Gateways Modify, Egress Gateways Delete, Egress Credentials Create, Egress Credentials Modify and Egress Credentials Delete require Egress Providers Modify.
• Servers View and Server Templates View requires Server Pools View and Zones View

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:

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

Batch Create Users

Create multiple users by uploading a CSV file.

Note

This endpoint expects a multi-part form upload containing the CSV file contents.

See the Users Bulk Import section for details on the CSV file format.

Permission Required:

• Users Create
• Groups Modify if using group_* columns
• Groups Modify System if those groups include system groups like Administrators.

POST /api/public/batch_create_user

Example request:

Headers

Content-Type: multipart/form-data
api-key: <Developer API key ID>
api-key-secret: <Developer API key secret>

The CSV file content is expected in the file_content field.

file_content=<file contents>

The view query parameter controls the format of the data returned. Validation data will always be returned in the csv_validation_data field when there is an error. In the success case:

View Value	Default	Response.csv_validation_data	Response.resources
api	No	null	Contains db results
table	Yes	Contains validation results	null
all	No	Contains validation results	Contains db results

Example success response:

Request was made with ?view=all

{
    "error_message": null,
    "csv_validation_data": {
      "headers": ["username", "realm", "first_name", "last_name", "phone_number", "organization", "force_password_reset", "city", "state", "country", "email", "group_1"],
      "total_errors": 0,
      "global_errors": [],
      "total_rows": 1,
      "row_data": [
        {
          "total_errors": 0,
          "contextual_errors": [],
          "fields": [
            {
              "field": "username",
              "value": "test_user1@example.com"
            },
            {
              "field": "realm",
              "value": "local"
            },
            {
              "field": "first_name",
              "value": "Bob"
            },
            {
              "field": "last_name",
              "value": "Williams"
            },
            {
              "field": "phone_number",
              "value": "+1 234-567-8900"
            },
            {
              "field": "organization",
              "value": "Test Org"
            },
            {
              "field": "force_password_reset",
              "value": true
            },
            {
              "field": "city",
              "value": "Springfield"
            },
            {
              "field": "state",
              "value": "IL"
            },
            {
              "field": "country",
              "value": "USA"
            },
            {
              "field": "email",
              "value": "test_user1@example.com"
            },
            {
              "field": "group_1",
              "value": "GroupA"
            }
          ]
        }
      ],
      "file_bom": ""
    },
    "resources": {
        "users": [
            {
                "user_id": "09b91b1fb9d1447e91fba42fe288aa1c",
                "username": "test_user1@example.com",
                "locked": false,
                "failed_pw_attempts": 0,
                "plan_start_date": null,
                "plan_end_date": null,
                "plan_id": null,
                "anonymous": false,
                "first_name": "Bob",
                "last_name": "Williams",
                "phone": "+1 234-567-8900",
                "organization": "Test Org",
                "notes": null,
                "realm": "local",
                "saml_id": null,
                "oidc_id": null,
                "subscription_id": null,
                "company_id": null,
                "company": null,
                "program_id": null,
                "disabled": false,
                "created": "2025-07-24 20:48:37.695074",
                "password_set_date": null,
                "city": "Springfield",
                "state": "IL",
                "country": "USA",
                "email": "test_user1@example.com",
                "custom_attribute_1": null,
                "custom_attribute_2": null,
                "custom_attribute_3": null,
                "crypt_password": "**********",
                "crypt_salt": "**********",
                "groups": [
                        {
                            "name": "All Users",
                            "group_id": "68d557ac4cac42cca9f31c7c853de0f3"
                        },
                        {
                            "name": "GroupA",
                            "group_id": "0fb98d3c248b4cb8a0e905d549777f38"
                        }
                ]
            }
        ]
    }
}

Example error response - bad permissions

Status Code: 401

{
  "error_message": "Access Denied."
}

Example error response - unparsable CSV data

Status Code: 400

{
  "error_message": "Invalid file format: ...",
  "csv_validation_data": null
}

Example error response - invalid CSV data

Status Code: 400

{
  "error_message": "Failed to import CSV file data",
  "csv_validation_data": {
    "headers": ["username", "realm", "first_name", "group_1"],
    "total_errors": 3,
    "global_errors": [
      {
        "code": "CSV_ERROR_002",
        "message": "Missing required fields",
        "field_names": ["required_field_1"]
      }
    ],
    "total_rows": 1,
    "row_data": [
      {
        "total_errors": 2,
        "contextual_errors": [
          {
            "code": "CSV_ERROR_011",
            "message": "Groups(['missing_group_a']) not found",
            "fields": ["group_*"]
          }
        ],
        "fields": [
          {
            "field": "username",
            "value": "test_user1@example.com"
          },
          {
            "field": "realm",
            "value": "locals",
            "error": {
              "code": "CSV_ERROR_009",
              "message": "Input should be 'ldap', 'local', 'oidc' or 'saml'"
            }
          },
          {
            "field": "first_name",
            "value": "Bob"
          },
          {
            "field": "group_1",
            "value": "missing_group_a"
          }
        ]
      }
    ],
    "file_bom": ""
  }
}

See the Appendix: CSV Error Codes for a complete list of validation error codes.

Get User

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

Permission Required: Users View. Additionally, Servers View to receive assigned server information.

POST /api/public/get_user

Example request:

{
    "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
                }
            }
        ],
        "assigned_servers": [
            {
                "server_id": "4afd4760-f4b9-400b-98e7-a4c678540e63",
                "hostname": "persistant.host.local",
                "friendly_name": "Persistant Server A",
                "server_assignment_enabled": true
            }
        ],
        "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. Additionally, Servers View to receive assigned server information.

POST /api/public/get_users

Example request:

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

Example response:

{
    "users": [
        {
            "kasms": [],
            "assigned_servers": [],
            "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": [],
            "assigned_servers": [
                {
                    "server_id": "4afd4760-f4b9-400b-98e7-a4c678540e63",
                    "hostname": "persistant.host.local",
                    "friendly_name": "Persistant Server A",
                    "server_assignment_enabled": true
                }
            ],
            "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:

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

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

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

{
     "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,
        "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:

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

{}

Assign User to Server

Assigns a User to a Server in a Server Pool. The relationship between User and Server is many-to-many. See User-Server Assignment for more information.

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

POST /api/public/assign_user_server

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0"
    },
    "target_server": {
        "server_id": "4afd4760-f4b9-400b-98e7-a4c678540e63"
    }
}

Example response:

Status Code: 200

{
    "user_server_assignment": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0",
        "server_id": "4afd4760-f4b9-400b-98e7-a4c678540e63"
    }
}

Unassign User from Server

Unassigns a User from a Server in a Server Pool. See User-Server Assignment for more information.

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

POST /api/public/unassign_user_server

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "67d7c4e6-f891-4900-897f-ce5ed62fecc0"
    },
    "target_server": {
        "server_id": "4afd4760-f4b9-400b-98e7-a4c678540e63"
    }
}

Example response:

Status Code: 204 (No Content)

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 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:

{
    "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",
    "username": "1d47uudwcynkd2su",
    "status": "starting",
    "share_id": "fe9770a4",
    "user_id": "8affcdbc16fc4910acb8a6dc268cd7ed",
    "session_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiY2E4ODFkOGEtNzNhMi00M2IzLThkZmMtYzAxZGU4YmY5YzMyIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODI5NjEyfQ.UlHuZ7pSz2a74sqj8toyveKX2xmJMIapTD-e9x9fQZyXRiJv2J0jZ9g6sjLXxvtYgxtnK-0MMwMI80gLGSXapnB3JGur_4khQh-PnuQQP1o-KFM0_tTgs6O6OyXApli3x_ko9v5c_Ze-uCo2rJtjwHct7Y1HVa_pFBIBR8bvvfyigFm2DQjZ_eNTE9qxPGHtPocid_D-lg6hNWSIjMsCuUH5j7dcuS70D3kThkD98iPXlJAuUUqXqWGL5AnayPxDD7hRBPVNLuz1R2IO2rjQmkbXHY8XINLGTAunVGsIl6IEVCqKkFHwjDMmGn_jLgL9S4g7ZQEMm4wNBqh-EjSQLg", 
    "kasm_url": "/#/connect/kasm/9b50379d-d04c-4037-81ef-6ac77b696e22/766384b9955c42da905888f84db9660e/eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiY2E4ODFkOGEtNzNhMi00M2IzLThkZmMtYzAxZGU4YmY5YzMyIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODI5NjEyfQ.UlHuZ7pSz2a74sqj8toyveKX2xmJMIapTD-e9x9fQZyXRiJv2J0jZ9g6sjLXxvtYgxtnK-0MMwMI80gLGSXapnB3JGur_4khQh-PnuQQP1o-KFM0_tTgs6O6OyXApli3x_ko9v5c_Ze-uCo2rJtjwHct7Y1HVa_pFBIBR8bvvfyigFm2DQjZ_eNTE9qxPGHtPocid_D-lg6hNWSIjMsCuUH5j7dcuS70D3kThkD98iPXlJAuUUqXqWGL5AnayPxDD7hRBPVNLuz1R2IO2rjQmkbXHY8XINLGTAunVGsIl6IEVCqKkFHwjDMmGn_jLgL9S4g7ZQEMm4wNBqh-EjSQLg"
}

Arguments

Name	Type	Description
user_id	string	If specified, the Kasm session will be created under this user. If omitted, an anonymous user will be created and used.
image_id	string	The ID of the image to use for the Kasm session. If omitted, the default image set at the group or user level will be used.
enable_sharing	boolean	If set to true, the Kasm session will be created with sharing mode enabled by default.
kasm_url	string	If specified, the browser inside the session will navigate to this URL. Only applicable to browser-based images (e.g., Kasm Chrome, Firefox, Tor Browser).
environment	dict	Environment variables to inject into the created container session.
connection_info	dict	Custom RDP/VNC/SSH connection settings. Not applicable for container-based sessions.
client_language	string (optional)	Language to be passed as an environment variable to the Kasm session. Refer to "Valid Languages" documentation for accepted values.
client_timezone	string (optional)	Timezone to be passed as an environment variable to the Kasm session. Refer to "Valid Timezones" documentation for accepted values.
egress_gateway_id	string (optional)	ID of the Egress Gateway the session should connect to at launch. The user must have permission and an associated Egress Credential. Only applies to container-based sessions. See the Egress documentation for details.
persistent_profile_mode	string (optional)	Controls behavior of persistent profiles (only for container sessions with persistent profile path configured). Valid values: • Enabled: Uses a persistent profile. If it doesn't exist, it will be created. • Disabled: Does not load a persistent profile. • Reset: Deletes any existing profile and creates a new one.
rdp_client_type	string (optional)	Required when the Workspace image is an RDP Server and the RDP Client option is set to User Selectable. Valid values: • GUAC – Session is web-native. • RDP_CLIENT – User connects using an RDP client.
server_id	string (optional)	Only applicable for sessions using non-container-based Server Pools. Specifies the exact server in the pool to use for the session.

Response Format

Name	Type	Description
kasm_id	string	Returns the ID for the newly created Kasm.
session_token	string	Returns the JWT 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	The URL path to the specified Kasm in the form of /#/connect/kasm/<kasm_id>/<user_id>/<session_token>. Append this value to the current Kasm Workspaces server address to create a full URL for accessing the Kasm. Directing the user's browser to the full URL will connect them to the Kasm session.

Warning

The kasm_url and resulting full URL should not be re-used for different users.

Unstructured Notes: 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.

The returned kasm_url is applicable to web native sessions, users can be directed to the returned URL once the session status is running as returned by the get_kasm_status API call. For RDP native clients, an additional API call is needed to get_rdp_client_connection_info in order to retrieve the RDP file or URL.

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:

{
    "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/9b50379d-d04c-4037-81ef-6ac77b696e22/766384b9955c42da905888f84db9660e/eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiY2E4ODFkOGEtNzNhMi00M2IzLThkZmMtYzAxZGU4YmY5YzMyIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODI5NjEyfQ.UlHuZ7pSz2a74sqj8toyveKX2xmJMIapTD-e9x9fQZyXRiJv2J0jZ9g6sjLXxvtYgxtnK-0MMwMI80gLGSXapnB3JGur_4khQh-PnuQQP1o-KFM0_tTgs6O6OyXApli3x_ko9v5c_Ze-uCo2rJtjwHct7Y1HVa_pFBIBR8bvvfyigFm2DQjZ_eNTE9qxPGHtPocid_D-lg6hNWSIjMsCuUH5j7dcuS70D3kThkD98iPXlJAuUUqXqWGL5AnayPxDD7hRBPVNLuz1R2IO2rjQmkbXHY8XINLGTAunVGsIl6IEVCqKkFHwjDMmGn_jLgL9S4g7ZQEMm4wNBqh-EjSQLg",
    "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

Name	Type	Description
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

Name	Type	Description
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>
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:

{
    "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": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiZjFmZWFiY2MtNzU2Yi00MmZiLThiODUtODQ1ODE0MjdjMzNjIiwiYXV0aG9yaXphdGlvbnMiOlsxMDBdLCJleHAiOjE3MTE4NDc0NDB9.agZubjVeUUmG3dV6IukU5JsOMoH4K9k98k8WjTecCBdgjhC0lEKBvs7257X6cbeavZE0ZRjKHkbrUlmJ18eVdss1j79DVdIyEqHVQX2ue9h2AKVYIi4LBGYJd-PXUeUadVUOopRrZcww1MgTTyDTqB8ZGbn3lR_wd2Jrk0_QMx5n046ShE7lL9De66_AapRbVk_vhWcMEdWHK7QTmMn7Qn1bHKFiDss9IhFVdzk6oSryaTgnK6YrvY7S7OOMcSXuaa2MEzYUCKmyau1LBCHyk_OpeHtJhrlw4gZXWerakfKlh6ghO2CnsK7MfPIYner6oimyLbXmztDbTrQD0yD4xA",
    "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/a35f030c/4cea872ff36044c690751e41ba2ec0e1/eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiZjFmZWFiY2MtNzU2Yi00MmZiLThiODUtODQ1ODE0MjdjMzNjIiwiYXV0aG9yaXphdGlvbnMiOlsxMDBdLCJleHAiOjE3MTE4NDc0NDB9.agZubjVeUUmG3dV6IukU5JsOMoH4K9k98k8WjTecCBdgjhC0lEKBvs7257X6cbeavZE0ZRjKHkbrUlmJ18eVdss1j79DVdIyEqHVQX2ue9h2AKVYIi4LBGYJd-PXUeUadVUOopRrZcww1MgTTyDTqB8ZGbn3lR_wd2Jrk0_QMx5n046ShE7lL9De66_AapRbVk_vhWcMEdWHK7QTmMn7Qn1bHKFiDss9IhFVdzk6oSryaTgnK6YrvY7S7OOMcSXuaa2MEzYUCKmyau1LBCHyk_OpeHtJhrlw4gZXWerakfKlh6ghO2CnsK7MfPIYner6oimyLbXmztDbTrQD0yD4xA"
}

Arguments

Name	Type	Description
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.

Response Format

Name	Type	Description
current_time	string	The UTC timestamp at which the API call was received.
kasm	object	A JSON object containing all current metadata and configuration details about the Kasm session.
kasm_url	string	A URL path used to access the specified shared Kasm session. The path should be appended to your Kasm server address. Format: /#/connect/join/<share_id>/<user_id>/<session_token>. Note: This link is user-specific and should not be reused for different users.
session_token	string	JWT token generated for the user, used for authorization when connecting to the Kasm session.
username	string	The username of the specified or newly created user.
user_id	string	The user ID of the specified or newly created user.

Get RDP Client Connection Info

After creating a session that requires the user to connect via an RDP native client, this API call allows you to retrieve a URL or file used by the RDP client to connect. Some clients, such as MacOS, allow opening the RDP client using a URL, while other clients, such as Windows, require downloading the RDP file and having the user opening the downloaded file. The DevAPI cannot determine what the client supports, it is up to your code to determine which format to request for the client. The file method is supported by most clients, while the url method provides a better user experience, but may not be supported. You are responsible for writing client side code to take the returned file or url data and either creating a download with the returned content or launching a window with the returned url.

Permission Required: Users Auth Session and User

POST /api/public/get_rdp_client_connection_info

Example request:

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

Example response - File:

{
    "file": "full address:s:myrdpgateway.com\r\nusername:s:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJrYXNtX2lkIjoiY2IzYTU1OGUtNjY3OS00NjMxLTk1M2YtMGUwOGY0OTA0YjBkIiwia2FzbV9jbGllbnRfa2V5IjpudWxsLCJpcCI6IjEyOS4yMTMuMTQxLjMxIiwiZXhwIjoxNzI0NDMyMzk2LCJhdXRob3JpemF\r\ndomain:s:0aW9ucyI6WzkxXX0._Y2B26S4mT7ZfJIbtVnPzXLUn3j-VIZngUl6zKUkmJeXjXO73GJVe1dzU5n1tuD75fFjw_3ELfbH7xmQS4jPzA\r\nconnection type:i:6\r\nnetworkautodetect:i:1\r\nbandwidthautodetect:i:1\r\nscreen mode id:i:2\r\nuse multimon:i:0\r\nsinglemoninwindowedmode:i:1\r\nkeyboardhook:i:2\r\ndisable full window drag:i:1\r\ndisable menu anims:i:1\r\nbitmapcachepersistenable:i:1\r\nsession bpp:i:32\r\ndynamic resolution:i:1\r\nautoreconnection enabled:i:1\r\nvideoplaybackmode:i:1\r\nallow desktop composition:i:1\r\ndisable themes:i:0\r\ndisable cursor setting:i:0\r\nallow font smoothing:i:1\r\ngatewayhostname:s:myrdpgateway.com\r\ngatewaycredentialssource:i:5\r\ngatewayusagemethod:i:1\r\ngatewayprofileusagemethod:i:1\r\ngatewaybrokeringtype:i:0\r\ngatewayaccesstoken:s:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJrYXNtX2lkIjoiY2IzYTU1OGUtNjY3OS00NjMxLTk1M2YtMGUwOGY0OTA0YjBkIiwia2FzbV9jbGllbnRfa2V5IjpudWxsLCJpcCI6IjEyOS4yMTMuMTQxLjMxIiwiZXhwIjoxNzI0NDMyMzk2LCJhdXRob3JpemF0aW9ucyI6WzkxXX0._Y2B26S4mT7ZfJIbtVnPzXLUn3j-VIZngUl6zKUkmJeXjXO73GJVe1dzU5n1tuD75fFjw_3ELfbH7xmQS4jPzA\r\nalternate full address:s:myrdpgateway.com\r\nsignscope:s:Full Address,Alternate Full Address,AutoReconnection Enabled,GatewayHostname,GatewayUsageMethod,GatewayProfileUsageMethod,GatewayCredentialsSource\r\nsignature:s:AQABAAEAAAA/BQAAMIIFOwYJKoZIhvcNAQcCoIIFLDCCBSgCAQExDzANBglghkgBZQMEAgEFADALBgkqhkiG9w0BBwGgggL3MIIC8zCCAdugAwIBAgIUaI7fR/Q9ye6euOQnARerWpON3XwwDQYJKoZIhvcNAQELBQAwJzElMCMGA1UEAwwcS2FzbSBSRFAgU2lnbmluZyBDZXJ0aWZpY2F0ZTAeFw0yNDA4MjMxNjI4MDRaFw0yNTA4MjMxNjI4MDRaMCcxJTAjBgNVBAMMHEthc20gUkRQIFNpZ25pbmcgQ2VydGlmaWNhdGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDF49LtjS9G+NUh+vz3Gaj70tqPFcUKDk51wU3YxnnVeuGZzxR/iW0rdqeOEyl8aXj6pBQCvM4t2G+eTvw8wT1CQ/ftNGLsGLK76hql1F9AGf383BNoIpz0Q5UGHNDEzSfDGcnQbaT6ebMpmVSBr3IvakIvllo5oPA4SR5YVll76KLKXmeG6W/vsp5u/VoRo5HjqONIx1eDjYBwxDyJMlLDklc2VXBew4/AvAMZ2VX91vH5YnWHvckjGaGUfrMjx5QqPW+a+p4rQlOqvUBNtc8JSbgcIqxIbT4y663mv2jzM74/NcfuR616NvObJJtgMtdoJ1N2LBSsKw1gDcprFEaXAgMBAAGjFzAVMBMGA1UdJQQMMAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQARVRSL8MjZhjTqCgYlGWszA6bKh3jgjWE1ThPLl5VeRLUp9p2NLXxGaDzOakjXsZWWb8RQZTAGWjLrgU47D/WTGOVbrIpior4LHIyPkgWICUfzGKJA31MrLREKRZrlvsjvaP20CSRc9KIfefosEcDfttEBQI8pAiXZDqAXeXG5nz2f9BS5DenkK/s6yv2+LhHs2j5ea1wMwdVKh3ym4l3uqybSzDtRGHesZN3dhk+2uTq1G5VhWCFCCs96Wkh4F4sGfDwqTTcKZ17XiSp6hpFT6FBYOJFt+wL0PTS60fio1TDWjSY0yPWuH9Q7l1hwKnzuejwn7wLl9j5PiR7T4whDMYICCDCCAgQCAQEwPzAnMSUwIwYDVQQDDBxLYXNtIFJEUCBTaWduaW5nIENlcnRpZmljYXRlAhRojt9H9D3J7p645CcBF6tak43dfDANBglghkgBZQMEAgEFAKCBmzAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yNDA4MjMxNjU0NTZaMC8GCSqGSIb3DQEJBDEiBCDZceUCavSWsoTcIXgZu7WRh6eyVM9cwbPcoOVJmzx0NDAwBgkqhkiG9w0BCQ8xIzAhBglghkgBZQMEASoGCWCGSAFlAwQBFgYJYIZIAWUDBAECMA0GCSqGSIb3DQEBCwUABIIBAAKUyHSVmLYwogu7H91sY7NBE3+fpBhIC+nxz5vKsC/698QjtlmmhKyyeCdclxgVufoSWj6jkCgTs45ocQE2/+30f7PCSt8vSK+3FWXn140DeEg60bcQX8+ke4htJBv1H2aRjeabD531zzn2bgi45OYBoBHu78s3cI2/B8xFaikxc90x5/xUNCNiVhJgJ+IajXCRmrDKT/Cwby9JEW0aQYS0BLK0/CRrN5V9QWicUi0tbDoVy4z9BfVbceXK6XGyI+mtV1Jk1K43Ww2xqO1gnOjmyEiwuIofSOzSV+dcWc8XCH9T4P60OUVNuYIRw9YFbIbOabtm67+3venea77ZIkg=\r\n"
}

Example response - URL:

{
    "url": "rdp://full+address=s:myrdpgateway.com&username=s:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJrYXNtX2lkIjoiY2IzYTU1OGUtNjY3OS00NjMxLTk1M2YtMGUwOGY0OTA0YjBkIiwia2FzbV9jbGllbnRfa2V5IjpudWxsLCJpcCI6IjEyOS4yMTMuMTQxLjMxIiwiZXhwIjoxNzI0NDMyMzgzLCJhdXRob3JpemF&domain=s:0aW9ucyI6WzkxXX0.3uAxQGIOMEHw8InGXU89Jw9vTBzgIPA42s3uYHMRaj2W1ZkhX1ff0i5dtgtuBlNvupPP7KdWBngGjoVN4YqHdQ&connection+type=i:6&networkautodetect=i:1&bandwidthautodetect=i:1&screen+mode+id=i:2&use+multimon=i:0&singlemoninwindowedmode=i:1&keyboardhook=i:2&disable+full+window+drag=i:1&disable+menu+anims=i:1&bitmapcachepersistenable=i:1&session+bpp=i:32&dynamic+resolution=i:1&autoreconnection+enabled=i:1&videoplaybackmode=i:1&allow+desktop+composition=i:1&disable+themes=i:0&disable+cursor+setting=i:0&allow+font+smoothing=i:1&gatewayhostname=s:myrdpgateway:443&gatewaycredentialssource=i:5&gatewayusagemethod=i:1&gatewayprofileusagemethod=i:1&gatewaybrokeringtype=i:0&gatewayaccesstoken=s:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJrYXNtX2lkIjoiY2IzYTU1OGUtNjY3OS00NjMxLTk1M2YtMGUwOGY0OTA0YjBkIiwia2FzbV9jbGllbnRfa2V5IjpudWxsLCJpcCI6IjEyOS4yMTMuMTQxLjMxIiwiZXhwIjoxNzI0NDMyMzgzLCJhdXRob3JpemF0aW9ucyI6WzkxXX0.3uAxQGIOMEHw8InGXU89Jw9vTBzgIPA42s3uYHMRaj2W1ZkhX1ff0i5dtgtuBlNvupPP7KdWBngGjoVN4YqHdQ"
}

Arguments

Name	Type	Description
user_id	string	The user ID associated with the requested kasm.
kasm_id	string	The ID of the desired Kasm.
connection_type	string	Must be set to file or url. For file, the returned value contains the file contents of an RDP file. For url the repsonse contains a URL, which the user can be directed to, which will open their native RDP client.

Response Format

Name	Type	Description
file	string	The file contents for an RDP file.
url	string	The url to launch the client's native RDP client with connection details.

Get Kasms

Retrieve a list of live sessions.

Permission Required: Sessions View

POST /api/public/get_kasms

Example request:

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

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

}

Example response:

{}

Arguments

Name	Type	Description
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:

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

Example response:

{
    "usage_reached": false
}

Arguments

Name	Type	Description
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:

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

Name	Type	Description
kasm_id	string	The ID of the Kasm session to retrieve statistics for.
user_id	string	The ID of the user who owns the session.
client	string	Specifies which client to retrieve stats for. Options include: • auto (default) – Automatically selects the client-side stats for the owner of the Kasm session. • none – Retrieves server-side stats only. • all – Retrieves stats for all connected websocket clients. • <user_websocket_id> – Specifies a specific KasmVNC websocket client ID, e.g., 172.18.0.8_1627985086.157123::websocket.

Response Format

Name	Type	Description
resx	integer	Horizontal resolution (in pixels) of the processed frame.
resy	integer	Vertical resolution (in pixels) of the processed frame.
changed	integer	Percentage of the frame that changed compared to the previous frame.
server_time	integer	Total wall-clock time (in milliseconds) taken to process the frame on the server. Reflects total time, not CPU time, and includes multi-threaded processing.
analysis	integer	Time in milliseconds taken to pre-process the frame and detect changes.
encoding_total	integer	Wall-clock time (in milliseconds) to encode the frame. Encoding uses multiple threads and a mix of JPEG and WebP encoders.
videoscaling	integer	Time in milliseconds taken to scale the frame during video mode.
tightjpegencoder	integer	Aggregate CPU time (in milliseconds) used by all threads to encode JPEG rects. Not equivalent to wall-clock time.
tightwebpencoder	integer	Aggregate CPU time (in milliseconds) used by all threads to encode WebP rects. Not equivalent to wall-clock time.
clients	array	Array of client-side stats. Each object contains metrics such as ping, which represents the round-trip time in milliseconds. Divide by two for one-way latency.

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:

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

Name	Type	Description
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.
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:

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

Name	Type	Description
kasm_id	string	The ID of the Kasm session for which the expiration update is issued.
user_id	string	The ID of the user to whom the session belongs.
width	integer	The target width of the image. Default is 300.
height	integer	The target height of the image. This value may be overridden to preserve aspect ratio based on the provided width.

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:

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

Name	Type	Description
kasm_id	string	The ID of the Kasm session for which the expiration update is being issued.
user_id	string	The ID of the user to whom the session belongs.
exec_config	dict	Dictionary of execution settings and the command to run in the session container.
exec_config.cmd	string	The command to execute inside the user's container.
exec_config.environment	dict	Environment variables to set for the exec session.
exec_config.workdir	string	The working directory path for the exec session inside the container.
exec_config.privileged	bool	If true, runs the exec session with privileged permissions.
exec_config.user	string	The user to run the command as. By default, the session runs as the sandboxed user. Set to "root" to run as root, which disables sandbox protections. Any value other than "root" or omitted may cause the command to fail.

Response Format

Name	Type	Description
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.
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_viewers=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_viewers=1

Hides the list of viewers 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:

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

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

Name	Type	Description
target_kasm_id	string	The ID of the kasm to get the recordings for
preauth_download_link	bool	whether or not to generate preauth download links for the recording clips. Defaults to False

Response Format

Name	Type	Description
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:

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

Name	Type	Description
target_kasm_ids	array	List of IDs of the kasms to get the recordings for
preauth_download_link	bool	whether or not to generate preauth download links for the recording clips. Defaults to False

Response Format

Name	Type	Description
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:

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

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

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

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

Name	Type	Description
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.

Response Format

Name	Type	Description
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:

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

Name	Type	Description
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:

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

Name	Type	Description
target_staging_config.staging_config_id	string	The ID of the staging config to be updated.

Response Format

Name	Type	Description
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:

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

Name	Type	Description
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	Number of sessions the system will attempt to keep staged at all times.
target_staging_config.expiration	integer	Time in hours after which unassigned staged sessions expire and are re-created.
target_staging_config.allow_kasm_audio	bool	Enables audio streaming from the session to the user.
target_staging_config.allow_kasm_uploads	bool	Allows users to upload files from their local computer to the session using the upload widget.
target_staging_config.allow_kasm_downloads	bool	Allows users to download files from the session to their local computer via the download widget.
target_staging_config.allow_kasm_clipboard_down	bool	Enables copying data from the session to the user's clipboard.
target_staging_config.allow_kasm_clipboard_up	bool	Enables copying data from the user's clipboard into the session.
target_staging_config.allow_kasm_microphone	bool	Allows the user to pass their local microphone into the session.

Response Format

Name	Type	Description
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:

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

Name	Type	Description
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 to associate with the staging config.
target_staging_config.image_id	string	The Image ID to use for the staging config.
target_staging_config.num_sessions	integer	Number of sessions the system will attempt to keep staged at all times.
target_staging_config.expiration	integer	Duration in hours after which unassigned staged sessions expire and are recreated.
target_staging_config.allow_kasm_audio	bool	Enables audio streaming from the staged session to the user.
target_staging_config.allow_kasm_uploads	bool	Allows users to upload files from their local computer to the session using the control panel.
target_staging_config.allow_kasm_downloads	bool	Allows users to download files from the session to their local computer using the control panel.
target_staging_config.allow_kasm_clipboard_down	bool	Enables copying data from the session to the user’s local clipboard.
target_staging_config.allow_kasm_clipboard_up	bool	Enables copying data from the user’s clipboard into the session.
target_staging_config.allow_kasm_microphone	bool	Allows users to pass their local microphone input into the session.

Response Format

Name	Type	Description
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:

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

Example response:

{}

Arguments

Name	Type	Description
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:

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

Name	Type	Description
brief	bool	Limit the information returned for each zone.

Response Format

Name	Type	Description
zones	json object	A list of Deployment Zones.

Servers

Servers are non-docker-agent hosts that run workspaces. For example, a workstation that is accessible via SSH.

Batch Create Servers

Create multiple (Server Pool) servers by uploading a CSV file.

Note

This endpoint expects a multi-part form upload containing the CSV file contents.

See the Servers Bulk Import section for details on the CSV file format.

Permission Required:

• Servers Create
• Users Modify if using the assigned_username column
• Users Modify Admin if those users include system / admin users.

POST /api/public/batch_create_server

Example request:

Headers

Content-Type: multipart/form-data
api-key: <Developer API key ID>
api-key-secret: <Developer API key secret>

The CSV file content is expected in the file_content field.

file_content=<file contents>

The view query parameter controls the format of the data returned. Validation data will always be returned in the csv_validation_data field when there is an error. In the success case:

View Value	Default	Response.csv_validation_data	Response.resources
api	No	null	Contains db results
table	Yes	Contains validation results	null
all	No	Contains validation results	Contains db results

Example success response:

Request was made with ?view=all

{
    "error_message": null,
    "csv_validation_data": {
        "headers": ["name", "ip_hostname", "port", "zone_name", "connection_type", "connection_credential_type", "use_user_private_key", "pool_id", "assigned_username", "labels"],
        "total_errors": 0,
        "global_errors": [],
        "total_rows": 1,
        "row_data": [
            {
                "total_errors": 0,
                "contextual_errors": [],
                "fields": [
                    {
                        "field": "name",
                        "value": "Bob's Desktop"
                    },
                    {
                        "field": "ip_hostname",
                        "value": "bob1.local"
                    },
                    {
                        "field": "port",
                        "value": "22"
                    },
                    {
                        "field": "zone_name",
                        "value": "default"
                    },
                    {
                        "field": "connection_type",
                        "value": "SSH"
                    },
                    {
                        "field": "connection_credential_type",
                        "value": "STATIC"
                    },
                    {
                        "field": "use_user_private_key",
                        "value": true
                    },
                    {
                        "field": "pool_id",
                        "value": "ae838047842840908b6dcb7ad1101626"
                    },
                    {
                        "field": "assigned_username",
                        "value": "test_user1@example.com"
                    },
                    {
                        "field": "labels",
                        "value": ["shared", "personal"]
                    }
                ]
            }
        ],
        "file_bom": ""
    },
    "resources": {
        "servers": [
            {
                "server_id": "f542db0e23234f0096dd9fba78ac66a6",
                "created": "2025-07-24 21:59:11.870792",
                "server_type": "Desktop",
                "agent_version": null,
                "container_limit": 0,
                "cores": 0,
                "docker_images": {},
                "hostname": "bob1.local",
                "instance_id": null,
                "last_reported": null,
                "memory": 0,
                "operational_status": "running",
                "provider": null,
                "docker_info": {},
                "memory_stats": {},
                "disk_stats": {},
                "network_interfaces": {},
                "cpu_percent": 0.0,
                "last_reported_elapsed": null,
                "cores_override": 0,
                "memory_override": 0,
                "manager_id": null,
                "manager": null,
                "core_calculations": {
                    "percentage": 0,
                    "used": 0,
                    "max": 0
                },
                "memory_calculations": {
                    "percentage": 0,
                    "used": 0,
                    "max": 0
                },
                "public_ip": null,
                "enabled": true,
                "prune_images_mode": "Aggressive",
                "gpus": 0,
                "gpu_info": {},
                "gpu_percent": {},
                "gpu_memory_used_percent": {},
                "gpu_temp": {},
                "gpus_override": 0,
                "connection_type": "SSH",
                "connection_info": null,
                "max_simultaneous_sessions": 1,
                "zone_id": "189c9a9b288c4dd49fc1274cc527a49d",
                "server_pool_id": "ae838047842840908b6dcb7ad1101626",
                "server_pool_name": "local-individual-machines",
                "zone_name": "default",
                "friendly_name": "Bob's Desktop",
                "is_autoscaled": false,
                "connection_username": null,
                "connection_password": null,
                "connection_port": 22,
                "connection_private_key": null,
                "use_user_private_key": true,
                "connection_passphrase": null,
                "agent_installed": false,
                "connection_credential_type": "STATIC",
                "connection_sso_username_domain": null,
                "max_simultaneous_users": 1,
                "labels": [
                    "shared",
                    "personal"
                ],
                "inherited_labels": [
                    "shared",
                    "personal"
                ],
                "assigned_users": [
                    {
                        "user_id": "e39cb0579edb488c91f7600208a37243",
                        "username": "test_user1@example.com"
                    }
                ]
            }
        ]
    }
}

Example error response - bad permissions

Status Code: 401

{
  "error_message": "Access Denied."
}

Example error response - unparsable CSV data

Status Code: 400

{
  "error_message": "Invalid file format: ...",
  "csv_validation_data": null
}

Example error response - invalid CSV data

Status Code: 400

{
  "error_message": "Failed to import CSV file data",
  "csv_validation_data": {
    "headers": ["zone_name", "ip_hostname", "port", "connection_type", "connection_credential_type", "pool_id", "labels"],
    "total_errors": 3,
    "global_errors": [
      {
        "code": "CSV_ERROR_002",
        "message": "Missing required fields",
        "field_names": ["name"]
      }
    ],
    "total_rows": 1,
    "row_data": [
      {
        "total_errors": 2,
        "contextual_errors": [
          {
            "code": "CSV_ERROR_012",
            "message": "ConnectionType(SSH) cannot use CredentialType(PROMPT_USER)",
            "fields": ["connection_type", "connection_credential_type"]
          }
        ],
        "fields": [
          {
            "field": "zone_name",
            "value": "default"
          },
          {
            "field": "ip_hostname",
            "value": "bob1.local"
          },
          {
            "field": "port",
            "value": "22"
          },
          {
            "field": "connection_type",
            "value": "SSH"
          },
          {
            "field": "connection_credentials_type",
            "value": "PROMPT_USER"
          },
          {
            "field": "pool_id",
            "value": "00001111222233334444555566667777",
            "error": {
              "code": "CSV_ERROR_011",
              "message": "ServerPool(00001111222233334444555566667777) does not exist"
            }
          },
          {
            "field": "labels",
            "value": ["shared", "personal"]
          }
        ],
        "file_bom": ""
      }
    ]
  }
}

See the Appendix: CSV Error Codes for a complete list of validation error codes.

Set Drain Server

Set server draining status.

Permission Required: Agents Modify

POST /api/public/set_drain_server

Example Request

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_server": {
        "server_id": "ae6478f8bc5d474889254c8d8b4a8538",
        "is_draining": true
    }
}

Example response:

{}

Arguments

Name	Type	Description
target_server.server_id	string	The ID of the Server to set draining status on.
target_server.is_draining	boolean	The draining status to set the server to.

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)
• session_jwt The JWT token used by clients for authentication.

Create Session Token

Create a session token for a user.

Permission Required: Users Auth Session

POST /api/public/get_session_token

Example request:

{
     "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",
        "session_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiNGYxNTY3MzUtNzEzMC00MmVjLTg1NWUtM2ExOWNiMTM1OGJiIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODMzMTUzfQ.oC1Nmm7GjIVr7k1MTnnKOFu7SDv3IC7g8WDiMA94vbhn2W6-uaghtvXv4tCd1aN9OOBxpmCsJeks4uatl56JFYYUx23eW13v_hZvXILOLf7WqQIv9cFAz5J_xlf63R3_NYggC16vL1u4Rf8c7hmDp0s-LSQrOy8uh91SYPijzkWE-NCXMUUCCCZWOu0UU6XuyMfF4uUtN0jHOzLU5XUZUXrMNKAPLnFe1HGnCXrW1TtdI2pAJTxMfSiuUMLzlKDpLyzDpPozBHDASH9XzGwkOqlLseYD137FVGYImrGZnf1Jp8H0JWQ7m7Z0BAf76tl7sKiNN2icPKBZryl2AbyeRg"
    }
}

Get Session Token

Query the information about a specific session token.

Permission Required: Users Auth Session

POST /api/public/get_session_token

Example request:

{
     "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",
        "session_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiNGYxNTY3MzUtNzEzMC00MmVjLTg1NWUtM2ExOWNiMTM1OGJiIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODMzMTUzfQ.oC1Nmm7GjIVr7k1MTnnKOFu7SDv3IC7g8WDiMA94vbhn2W6-uaghtvXv4tCd1aN9OOBxpmCsJeks4uatl56JFYYUx23eW13v_hZvXILOLf7WqQIv9cFAz5J_xlf63R3_NYggC16vL1u4Rf8c7hmDp0s-LSQrOy8uh91SYPijzkWE-NCXMUUCCCZWOu0UU6XuyMfF4uUtN0jHOzLU5XUZUXrMNKAPLnFe1HGnCXrW1TtdI2pAJTxMfSiuUMLzlKDpLyzDpPozBHDASH9XzGwkOqlLseYD137FVGYImrGZnf1Jp8H0JWQ7m7Z0BAf76tl7sKiNN2icPKBZryl2AbyeRg"
    }
}

Get Session Tokens

Get all session tokens for a user. This returns only the ID and the validity period of listed tokens, use the /api/public/get_session_token to retrieve the JWT token value of an individual token.

Permission Required: Users Auth Sessions

POST /api/public/get_session_tokens

Example request:

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

{
     "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",
        "session_jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzZXNzaW9uX3Rva2VuX2lkIjoiNGYxNTY3MzUtNzEzMC00MmVjLTg1NWUtM2ExOWNiMTM1OGJiIiwiYXV0aG9yaXphdGlvbnMiOlsxMDAsMjAwXSwiZXhwIjoxNzExODMzMjkyfQ.Oyo5OLUlGJtfTH-oX0KJK5BdK_s_LIZ17Trl8YyZBEqmgJIzFPdO_pwn3PjM4RW0KImZTnj-LCz1SmlR2oeRyP5GA8A2HbHTJRB_fmQIHhPnXNxOlmu0TEfXxykuXr930OH79QOxyF8xM7IzFf048bpmdrc_JsENryPDJYklZgGndTvoF4pwloU6K5EfoUSHrG-A29voFNwKfJhZ6nayWUxJtHuZkq3GZNZU2wayJls_3D4ojjDByZzUTDmLY15enJ3xhfJG0c0SJv5g-rQUo3rqTS11zOvQIAu9WLF2yJC9JzTIKL70oyzNRaStyrbgTYxr2IDGcXKzBq_QraGcpQ"
    }
}

Delete Session Token

Delete a single session token for the user.

Permission Required: User Auth Sessions

POST /api/public/delete_session_token

Example request:

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

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

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

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

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

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

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

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

Name	Type	Description
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:

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

Name	Type	Description
cast_config_id	string	The ID of the casting config to be queried.

Response Format

Name	Type	Description
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:

{
    "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 Jammy",
        "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

Name	Type	Description
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.

Response Format

Name	Type	Description
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:

{
    "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 Jammy",
        "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

Name	Type	Description
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.

Response Format

Name	Type	Description
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:

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

Example response:

{}

Arguments

Name	Type	Description
cast_config_id	string	The ID of the casting config to be queried.

Egress Providers

Get Egress Providers

Get existing Egress Providers.

Permission Required: Egress Providers View

GET /api/public/get_egress_providers

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}"
    "target_egress_provider": {
        "enabled": true
    }
}

Example response:

{
        "egress_providers": [
            {
                "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
                "created": "2024-04-09 20:16:33.122852",
                "name": "My Wireguard Provider",
                "egress_provider_type": "wireguard",
                "enabled": true
            },
            {
                "egress_provider_id": "94414e5939e74717a13b1cedfa39d95c",
                "created": "2024-04-17 16:17:42.855382",
                "name": "My OpenVPN Provider",
                "egress_provider_type": "openvpn",
                "enabled": true
            }
        ]
    }

Arguments

Name	Type	Description
target_egress_provider.egress_provider_type	string	The type of Egress Provider to filter on.
target_egress_provider.enabled	boolean	Wether the egress provider is enabled.
target_egress_provider.name	string	The name of the Egress Provider.
target_egress_provider.egress_provider_id	string	The egress_provider_id to filter on.

Response Format

Name	Type	Description
egress_providers	json object	A list of Egress Providers.

Create Egress Provider

Create a new Egress Provider.

Permission Required: Egress Providers Create

POST /api/public/create_egress_provider

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider": {
        "name": "My Wireguard Provider",
        "egress_provider_type": "wireguard",
        "enabled": true
    }
}

Example response:

{
    "egress_provider": {
        "egress_provider_id": "a9899290c1254763b2919d4467b5b795",
        "created": "2024-04-17 16:44:45.266496",
        "name": "test2",
        "egress_provider_type": "wireguard",
        "enabled": true
    }
}

Arguments

Name	Type	Description
target_egress_provider.egress_provider_type	string	The type of Egress Provider to be created.
target_egress_provider.enabled	boolean	Whether to enable the Egress Provider.
target_egress_provider.name	string	The name of the created Egress Provider.

Response Format

Name	Type	Description
egress_provider	json object	The created Egress Provider.

Update Egress Provider

Update an Egress Provider.

Permission Required: Egress Providers Modify

POST /api/public/update_egress_provider

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider": {
        "egress_provider_id": "a9899290c1254763b2919d4467b5b795",
        "name": "My Wireguard Provider",
        "egress_provider_type": "wireguard",
        "enabled": true
    }
}

Example response:

{
    "egress_provider": {
        "egress_provider_id": "a9899290c1254763b2919d4467b5b795",
        "created": "2024-04-17 16:44:45.266496",
        "name": "test2",
        "egress_provider_type": "wireguard",
        "enabled": true
    }
}

Arguments

Name	Type	Description
target_egress_provider.egress_provider_id	string	The ID of the desired Egress Provider to update.
target_egress_provider.egress_provider_type	string	The type of Egress Provider to be created.
target_egress_provider.enabled	boolean	Whether to enable the Egress Provider.
target_egress_provider.name	string	The name of the created Egress Provider.

Response Format

Name	Type	Description
egress_provider	json object	The created Egress Provider.

Delete Egress Provider

Delete an Egress Provider.

Permission Required: Egress Providers Delete

POST /api/public/delete_egress_provider

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider": {
        "egress_provider_id": "a9899290c1254763b2919d4467b5b795"
    }
}

Example response:

{}

Arguments

Name	Type	Description
target_egress_provider.egress_provider_id	string	The ID of the desired Egress Provider to delete.

Egress Gateway

Get Image Egress Gateways

Get a list of a User's Permitted Egress Gateways for a specific Image.

Permission Required: Egress Gateways View, Users View, Images View

GET /api/public/get_image_egress_gateways

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_user": {
        "user_id": "57ce33ab262a4e18825f68403c8adb91"
    },
    "target_image": {
        "image_id": "59d352ffd64b4ea2bbadb3324095c811"
    }
}

Example response:

{
    "egress_gateways": [
        {
            "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b",
            "egress_gateway_name": "NY22",
            "egress_credential_id": "b55fbf47f2f545ce87817bead6ce6ab9",
            "city": "New York",
            "country": "US",
            "egress_provider_name": "My Openvpn Provider"
        }
    ],
    "image_id": "59d352ffd64b4ea2bbadb3324095c811"
}

Arguments

Name	Type	Description
target_user.user_id	string	The ID of the User to get the list of Egress Gateways for.
target_image.image_id	string	The ID of the Image to get the list of Egress Gateways for.

Response Format

Name	Type	Description
egress_gateways	json list	A list of the Users's Egress Gateways for the requested Image, along with the name of the attached Egress Provider, and the egress_credential_id that is paired with the Egress Gateway. image_id string: The ID of the Image we retrieved the Egress Gateways for.
image_id	string	The ID of the Image we retrieved the Egress Gateways for.

Get Egress Gateways

Get existing Egress Gateways.

Permission Required: Egress Gateways View

GET /api/public/get_egress_gateways

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider": {
        "enabled": true
    }
}

Example response:

{
    "egress_gateways": [
        {
            "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b",
            "name": "NY22",
            "enabled": true,
            "country": "US",
            "city": "New York",
            "config": "# ==============================================================================\n...",
            "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
            "active_connections": 0
        },
        {
            "egress_gateway_id": "ae68af8807034bcdb217a905fea37200",
            "name": "NJ13",
            "enabled": true,
            "country": "United States ",
            "city": "Secaucus",
            "config": "[Interface]\n...",
            "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
            "active_connections": 0
        }
    ]
}

Arguments

• Optional

Name	Type	Description
target_egress_gateway.egress_provider_id	string	An Egress Provider ID to filter on.
target_egress_gateway.enabled	boolean	Whether the Egress Gateway is enabled.
target_egress_gateway.name	string	The name of the Egress Gateway.
target_egress_gateway.country	string	The country of the Egress Gateway.
target_egress_gateway.city	string	The city of the Egress Gateway.
target_egress_gateway.egress_gateway_id	string	An Egress Gateway ID to filter on.

Response Format

Name	Type	Description
egress_gateways	json object	A list of Egress Gateways

Create Egress Gateway

Create a new Egress Gateway.

Permission Required: Egress Gateway Create, Egress Providers Modify

POST /api/public/create_egress_gateway

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_gateway": {
        "enabled": true,
        "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
        "name": "NJ13",
        "country": "United States",
        "city": "Secaucus",
        "config": "[Interface]\n..."
    }
}

Example response:

{
    "egress_gateway": {
        "egress_gateway_id": "ae68af8807034bcdb217a905fea37200",
        "name": "NJ13",
        "enabled": true,
        "country": "United States",
        "city": "Secaucus",
        "config": "[Interface]\n#..."
        "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
        "active_connections": 0
    }
}

Arguments

Name	Type	Description
target_egress_gateway.egress_provider_id	string	The ID of the Egress Provider to attach the Egress Gateway to.
target_egress_gateway.enabled	boolean	Whether to enable the Egress Gateway.
target_egress_gateway.name	string	The name of the created Egress Gateway.
target_egress_gateway.country	string	The country of the created Egress Gateway.
target_egress_gateway.city	string	The city of the created Egress Gateway.
target_egress_gateway.config	string	The config of the created Egress Gateway. This is relevant for wireguard, openvpn, and custom provider types. For a Wireguard gateway the PrivateKey field can be omitted since it will be set by the Egress Credential.

Response Format

Name	Type	Description
egress_gateway	json object	The created Egress Gateway

Update Egress Gateway

Update an Egress Gateway.

Permission Required: Egress Gateways Modify, Egress Providers Modify

POST /api/public/update_egress_gateway

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_gateway": {
        "egress_gateway_id": "ae68af8807034bcdb217a905fea37200",
        "enabled": true,
        "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
        "name": "NJ13",
        "country": "United States",
        "city": "Secaucus",
        "config": "[Interface]\n..."
    }
}

Example response:

{
    "egress_gateway": {
        "egress_gateway_id": "ae68af8807034bcdb217a905fea37200",
        "name": "NJ13",
        "enabled": true,
        "country": "United States",
        "city": "Secaucus",
        "config": "[Interface]\n#..."
        "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
        "active_connections": 0
    }
}

Arguments

Name	Type	Description
target_egress_gateway.egress_gateway_id	string	The Id of the Egress Gateway to update.
target_egress_gateway.egress_provider_id	string	The ID of the Egress Provider to attach the Gateway to.
target_egress_gateway.enabled	boolean	Whether to enable the Egress Gateway.
target_egress_gateway.name	string	The name of the created Egress Gateway.
target_egress_gateway.country	string	The country of the created Egress Gateway.
target_egress_gateway.city	string	The city of the created Egress Gateway.
target_egress_gateway.config	string	The config of the created Egress Gateway. This is relevant for wireguard, openvpn, and custom provider types. For a Wireguard gateway the PrivateKey field can be omitted since it will be set by the Egress Credential.

Response Format

Name	Type	Description
egress_gateway	json object	The updated Egress Gateway

Delete Egress Gateway

Delete an Egress Gateway.

Permission Required: Egress Gateways Delete, Egress Providers Modify

POST /api/public/delete_egress_gateway

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_gateway": {
        "egress_gateway_id": "ae68af8807034bcdb217a905fea37200"
    }
}

Example response:

{}

Arguments

Name	Type	Description
target_egress_gateway.egress_gateway_id	string	The ID of the desired egress gateway to delete.

Egress Provider Mapping

Get Egress Provider Mappings

Get existing Egress Provider Mapping.

Permission Required: Egress Providers View

GET /api/public/get_egress_provider_mapping

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider_mapping": {
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null,
        "user_id": null
    }
}

Example response:

{
    "egress_provider_mappings": [
        {
            "egress_provider_mapping_id": "c46ed8c2a251495488b6f1c75bf328dd",
            "enabled": true,
            "created": "2024-04-17 17:32:42.167447",
            "user_id": null,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "image_id": null,
            "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
            "allow_all_gateways": true,
            "egress_provider": {
                "egress_provider_id": "c2c4e245ee5443fda4bc43d9eba4f198",
                "name": "My Wireguard Provider",
                "egress_provider_type": "wireguard"
            },
            "egress_gateways": []
        },
        {
            "egress_provider_mapping_id": "994e1ec54aeb4f74af3603c5c77919ba",
            "enabled": true,
            "created": "2024-04-16 16:10:34.624680",
            "user_id": null,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "image_id": null,
            "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
            "allow_all_gateways": false,
            "egress_provider": {
                "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
                "name": "My Openvpn Provider",
                "egress_provider_type": "openvpn"
            },
            "egress_gateways": [
                {
                    "name": "NY22",
                    "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b"
                }
            ]
        }
    ]
}

Arguments

Name	Type	Description
target_egress_provider_mapping.enabled	string	Whether the Egress Provider Mapping is enabled.
target_egress_provider_mapping.egress_provider_id	string	The Id of the egress_provider that the mapping is bound to.
target_egress_provider_mapping.group_id	string	The id of the group to get the egress_provider_mappings from.
target_egress_provider_mapping.user_id	string	The id of the user to get the egress_provider_mappings from.
target_egress_provider_mapping.image_id	string	The id of the image to get the egress_provider_mappings from.

Response Format

Name	Type	Description
egress_provider_mappings	json object	A list of Egress Provider Mappings.

Create Egress Provider Mapping

Create a new Egress Provider Mapping.

One of user_id, group_id, and image_id are required.

Permission Required: Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/create_egress_provider_mapping

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider_mapping": {
        "enabled": true,
        "user_id": null,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null,
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false,
        "selected_gateways": [
            "0f518584dfd6471c9f962858ddf0509b"
        ]
    }
}

Example response:

{
    "egress_provider_mapping": {
        "egress_provider_mapping_id": "a9017720bfb64a34b4d1147576c95c23",
        "enabled": true,
        "created": "2024-04-18 12:27:53.930234",
        "user_id": null,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null,
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false
    }
}

Arguments

Name	Type	Description
target_egress_provider_mapping.enabled	string	Whether to enable the Egress Provider Mapping.
target_egress_provider_mapping.egress_provider_id	string	The Id of the Egress Provider to attach the mapping to.
target_egress_provider_mapping.allow_all_gateways	boolean	Whether to allow all gateways in the provider to be a part of this mapping.
target_egress_provider_mapping.selected_gateways	list	Required when allow_all_gateways is false. List of Egress Gateway IDs that are to be a part of this mapping.
target_egress_provider_mapping.user_id	string	The ID of the user to attach the mapping to.
target_egress_provider.group_id	string	The ID of the group to attach the mapping to.
target_egress_provider.image_id	string	The ID of the image to attach the mapping to.

Response Format

Name	Type	Description
egress_provider_mapping	json object	The created Egress Provider Mapping

Update Egress Provider Mapping

Update an Egress Provider Mapping.

Permission Required: Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/update_egress_provider_mapping

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider_mapping": {
        "egress_provider_mapping_id": "a9017720bfb64a34b4d1147576c95c23",
        "enabled": true,
        "user_id": null,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null,
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false,
        "selected_gateways": [
            "0f518584dfd6471c9f962858ddf0509b"
        ]
    }
}

Example response:

{
    "egress_provider_mapping": {
        "egress_provider_mapping_id": "a9017720bfb64a34b4d1147576c95c23",
        "enabled": true,
        "created": "2024-04-18 12:27:53.930234",
        "user_id": null,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null,
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false
    }
}

Arguments

Name	Type	Description
target_egress_provider_mapping.egress_provider_mapping_id	string	The ID of the Egress Provider Mapping to update.
target_egress_provider_mapping.enabled	string	Whether to enable the Egress Provider Mapping.
target_egress_provider_mapping.egress_provider_id	string	The Id of the Egress Provider to attach the mapping to.
target_egress_provider_mapping.allow_all_gateways	boolean	Whether to allow all gateways in the provider to be a part of this mapping.
target_egress_provider_mapping.selected_gateways	list	Required when allow_all_gateways is false. List of Egress Gateway Ids that are to be a part of this mapping.
target_egress_provider_mapping.user_id	string	The ID of the user to attach the mapping to.
target_egress_provider.group_id	string	The ID of the group to attach the mapping to.
target_egress_provider.image_id	string	The ID of the image to attach the mapping to.

Response Format

Name	Type	Description
egress_provider_mapping	json object	The created egress provider mapping

Delete Egress Provider Mapping

Delete an Egress Provider mapping.

Permission Required: Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/delete_egress_provider_mapping

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_provider_mapping": {
        "egress_provider_mapping_id": "ae68af8807034bcdb217a905fea37200"
    }
}

Example response:

{}

Arguments

Name	Type	Description
target_egress_provider_mapping.egress_provider_mapping_id	string	The ID of the desired egress provider mapping to delete.

Egress Credentials

Get Egress Credentials

Get existing Egress Credentials.

Permission Required: Egress Credentials View

GET /api/public/get_egress_credentials

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_credential": {
        "user_id": null,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "image_id": null
    }
}

Example response:

{
    "egress_credentials": [
        {
            "egress_credential_id": "b55fbf47f2f545ce87817bead6ce6ab9",
            "name": "My Credential Name",
            "username": "myusername",
            "password": "**********",
            "enabled": true,
            "user_id": null,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "image_id": null,
            "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
            "allow_all_gateways": false,
            "wireguard_private_key": null,
            "tailscale_key": null,
            "limit_active_connections": true,
            "active_connection_limit": 1,
            "active_connections": 0,
            "custom_credential": null,
            "egress_provider": {
                "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
                "name": "My Openvpn Provider",
                "egress_provider_type": "openvpn"
            },
            "egress_gateways": [
                {
                    "name": "NY22",
                    "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b"
                }
            ]
        }
    ]
}

Arguments

Name	Type	Description
target_egress_credential.enabled	string	Whether the Egress Credential is enabled.
target_egress_credential.egress_provider_id	string	The Id of the Egress Provider that the Egress Credential is attached to.
target_egress_credential.name	string	The name of the Egress Credential.
target_egress_credential.user_id	string	The ID of the user the Egress Credential is attached to.
target_egress_credential.group_id	string	The ID of the group the Egress Credential is attached to.
target_egress_credential.image_id	string	The ID of the image the Egress Credential is attached to.

Response Format

Name	Type	Description
egress_credentials	json object	A list of Egress Credentials.

Create Egress Credentials

Create a new Egress Credential

One of user_id, group_id, and image_id are required.

Permission Required: Egress Credentials Create, Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/create_egress_credential

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_credential": {
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false,
        "selected_gateways": [
            "0f518584dfd6471c9f962858ddf0509b"
        ],
        "limit_active_connections": true,
        "enabled": true,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "user_id": null,
        "image_id": null,
        "username": "myusername",
        "password": "mypassword",
        "active_connection_limit": "1",
        "name": "My Credential Name"
    }
}

Example response:

{
    "egress_credentials": [
        {
            "egress_credential_id": "b55fbf47f2f545ce87817bead6ce6ab9",
            "name": "My Credential Name",
            "username": "myusername",
            "password": "**********",
            "enabled": true,
            "user_id": null,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "image_id": null,
            "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
            "allow_all_gateways": false,
            "wireguard_private_key": null,
            "tailscale_key": null,
            "limit_active_connections": true,
            "active_connection_limit": 1,
            "active_connections": 0,
            "custom_credential": null,
            "egress_provider": {
                "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
                "name": "My Openvpn Provider",
                "egress_provider_type": "openvpn"
            },
            "egress_gateways": [
                {
                    "name": "NY22",
                    "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b"
                }
            ]
        }
    ]
}

Arguments

Name	Type	Description
target_egress_credential.enabled	string	Whether to enable the Egress Credential.
target_egress_credential.egress_provider_id	string	The Id of the Egress Provider to attach the Egress Credential to.
target_egress_credential.allow_all_gateways	boolean	Whether to allow all gateways in the provider to be a part of this mapping.
target_egress_credential.limit_active_connections	boolean	Whether to limit the number of simultaneous active connections on this Egress Credential.
target_egress_credential.name	string	The name of this Egress Credential.
target_egress_credential.username	string	The username for this Egress Credential. Required when using openvpn.
target_egress_credential.password	string	The password for this Egress Credential. Required when using openvpn.
target_egress_credential.wireguard_private_key	string	The Wireguard private key for this Egress Credential. Required when using wireguard.
target_egress_credential.tailscale_key	string	The password of this Egress Credential. Required when using tailscale.
target_egress_credential.custom_credential	string	The custom_credentials of this Egress Credential. Required when using custom credential.
target_egress_credential.selected_gateways	list	Required when allow_all_gateways is false. List of Egress Gateway Ids that are to be a part of this credential.
target_egress_credential.user_id	string	The ID of the user to attach the credential to.
target_egress_credential.group_id	string	The ID of the group to attach the credential to.
target_egress_credential.image_id	string	The ID of the image to attach the credential to.
target_egress_credential.active_connections	integer	The number of simultaneous active connections allowed on this egress credential. Required when limit_active_connections is true.

Response Format

Name	Type	Description
egress_credential	json object	The created Egress Credential

Update Egress Credentials

Update a new Egress Credential

Permission Required: Egress Credentials Modify, Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/update_egress_credential

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_credential": {
        "egress_credential_id": "b55fbf47f2f545ce87817bead6ce6ab9",
        "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
        "allow_all_gateways": false,
        "selected_gateways": [
            "0f518584dfd6471c9f962858ddf0509b"
        ],
        "limit_active_connections": true,
        "enabled": true,
        "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
        "user_id": null,
        "image_id": null,
        "username": "myusername",
        "password": "mypassword",
        "active_connection_limit": "1",
        "name": "My Credential Name"
    }
}

Example response:

{
    "egress_credentials": [
        {
            "egress_credential_id": "b55fbf47f2f545ce87817bead6ce6ab9",
            "name": "My Credential Name",
            "username": "myusername",
            "password": "**********",
            "enabled": true,
            "user_id": null,
            "group_id": "68d557ac4cac42cca9f31c7c853de0f3",
            "image_id": null,
            "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
            "allow_all_gateways": false,
            "wireguard_private_key": null,
            "tailscale_key": null,
            "limit_active_connections": true,
            "active_connection_limit": 1,
            "active_connections": 0,
            "custom_credential": null,
            "egress_provider": {
                "egress_provider_id": "e6f5a178bcf747dd80feb641c04943a2",
                "name": "My Openvpn Provider",
                "egress_provider_type": "openvpn"
            },
            "egress_gateways": [
                {
                    "name": "NY22",
                    "egress_gateway_id": "0f518584dfd6471c9f962858ddf0509b"
                }
            ]
        }
    ]
}

Arguments

Name	Type	Description
target_egress_credential.egress_credential_id	string	The Id of the Egress Credential to update.
target_egress_credential.enabled	string	Whether to enable the Egress Credential.
target_egress_credential.egress_provider_id	string	The ID of the Egress Provider to attach the credential to.
target_egress_credential.allow_all_gateways	boolean	Whether to allow all gateways in the provider to be a part of this mapping.
target_egress_credential.limit_active_connections	boolean	Whether to limit the number of simultaneous active connections on this Egress Credential.
target_egress_credential.name	string	The name of this Egress Credential.
target_egress_credential.username	string	The username of this Egress Credential. Required when using openvpn.
target_egress_credential.password	string	The password of this Egress Credential. Required when using openvpn.
target_egress_credential.wireguard_private_key	string	The Wireguard private key of this Egress Credential. Required when using wireguard.
target_egress_credential.tailscale_key	string	The password of this Egress Credential. Required when using tailscale.
target_egress_credential.custom_credential	string	The custom_credentials of this Egress Credential. Required when using custom credential.
target_egress_credential.selected_gateways	list	Required when allow_all_gateways is false. List of Egress Gateway Ids that are to be a part of this credential.
target_egress_credential.user_id	string	The Id of the user to attach the credential to.
target_egress_credential.group_id	string	The Id of the group to attach the credential to.
target_egress_credential.image_id	string	The Id of the image to attach the credential to.
target_egress_credential.active_connections	integer	The number of simultaneous active connections allowed on this egress credential. Required when limit_active_connections is true.

Response Format

Name	Type	Description
egress_credential	json object	The updated Egress Credential

Delete Egress Credential

Delete an Egress Credential.

Permission Required: Egress Credential Delete, Egress Providers Modify, Users Modify if mapped to a User, Users Modify Admin if mapped to Admin User, Groups Modify if mapped to Group, Groups Modify System if mapped to a System Group, and Images Modify if mapped to an Image.

POST /api/public/delete_egress_provider_mapping

Example request:

{
    "api_key": "{{api_key}}",
    "api_key_secret": "{{api_key_secret}}",
    "target_egress_credential": {
        "egress_provider_mapping_id": "b55fbf47f2f545ce87817bead6ce6ab9"
    }
}

Example response:

{}

Arguments

Name	Type	Description
target_egress_credential.egress_credential_id	string	The ID of the desired Egress Credential to delete.

Appendix

CSV Error Codes

Bulk import routines that use CSV files use the same set of standard codes to indicate what errors occurred. Error codes will usually be accompanied by more detailed error messages and relevant field names.

Code	Error
CSV_ERROR_000	Pydantic Validation Error
CSV_ERROR_001	Wrong Data Type
CSV_ERROR_002	Missing required field
CSV_ERROR_003	Value too big
CSV_ERROR_004	Value too small
CSV_ERROR_005	Value too long
CSV_ERROR_006	Value too short
CSV_ERROR_007	Unsupported encoding
CSV_ERROR_008	Invalid format
CSV_ERROR_009	Nonexistent enum value
CSV_ERROR_010	Resource already exists
CSV_ERROR_011	Resource does not exist
CSV_ERROR_012	Invalid combination
CSV_ERROR_013	Data state does not permit the operation
CSV_ERROR_014	Invalid JSON
CSV_ERROR_015	Database Error