Using Undocumented APIs

Kasm publishes documentation on many of the most commonly used APIs by integrators. However, not all endpoints are officially documented.

The Workspaces platform is developed such that any JSON API utilized by the graphical user interface can also be instrumented via the developer API Keys.

Integrators should review and be comfortable with the concept of generating API keys and utilizing the documented endpoints before continuing.

The following guide will give an example of discovering and utilizing an undocumented API.

APIs, especially those not documented, are subject to change at each Kasm release. It is recommended that system integrators communicate with their Kasm representatives about the usage of undocumented endpoints or needs for additional endpoints.

Instructions

Identifying Endpoints

The best way to identify the endpoint needed, is to utilize the web browser’s developer tools.

Open the network tab, then instrument the desired functionality in the Kasm GUI. In this case we are creating a group. The API endpoint can be easily discerned from the captured traffic.

UI Function

Create Group API

As seen, the API being used by the UI is https://<server>/api/admin/create_group.

Selecting the Payload and Response tabs will show what is sent to the server and what is received.

API Request Body

API Response

Adjusting Endpoints for API Usage

In the previous example, we identified the desired endpoint (/api/admin/create_group ) as well as the request and response information.

Two changes need to be made for requests when utilizing.

Swapping out the username and token request properties for API Keys
- In the original request, the JSON body included username and token properties to authenticate the request.
- These properties should be replaced with api_key and api_key_secret to align with the Developer API Authentication scheme.
Changing the endpoint path.
- Any endpoint that uses /api/admin/ should be changed to /api/public/. In this case, the endpoint path used should be /api/public/create_group

Example

Putting it all together, the request for creating a group would be:

curl -k -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "target_group": {
      "name": "Example Group",
      "priority": "99",
      "description": "Example Description",
      "form_metadata": [
        {
          "key": "meta-key",
          "value": "meta-value"
        }
      ]
    },
    "api_key": "49T6buHW0V4t",
    "api_key_secret": "VjV8HJHH6ozWB29a60Q0mLsOEeKBmuMo"
  }' \
  https://192.168.56.107/api/public/create_group

Troubleshooting

Errors The full trace errors for API calls will not return to the calling client. For the complete error check the web UI logging screen for logs with level “Errors”.
These are examples of common error codes and error messages that are returned to the client.
- HTTP error 403 Permission Denied or {"error_message": "Unauthorized Action"}
  - This error indicates the API token or the user account does not have the appropriate group permissions.
  - Modify the permissions for the API token or a group owning the user account to include the required permission.
  - A list of group permissions can be found here (Group Permissions).
  - A list of API token permissions can be found here (API Permissions).
- HTTP error 404 Not Found
  - This error indicates the API endpoint is incorrect.
  - Verify the directory spelling and the path.
- HTTP error 500 Gateway Timeout
  - This error indicates the kasm domain (example https://DOMAIN) is incorrect or cannot be reached from the client.
  - Verify the client can reach the kasm domain.
  - Modify the network and security settings as necessary to allow the client to reach the kasm domain.
- <H1>Internal Error</H1>
  - This error indicates a generic timeout error when attempting the API call.
  - Check the web UI logging screen for error logs.
  - Verify the data posted contains all required object fields.
Important Notes
- When posting data to an API endpoint be sure to pass the entire object, including all required fields, to the endpoint.
- To get an example of the expected full object, use developer tools “Network” view to examine the function call and response with performing the action manually using the web UI.