About the KACE Systems Management Appliance API

About the KACE Systems Management Appliance API

The KACE Systems Management Appliance (SMA) API allows you to manage various aspects of the KACE SMA appliance data and its related information.

NOTE: Starting in version 12.1, the appliance API no longer returns nor requires the x-kace-csrf-token header. All that is required is that the x-kace-api-version header be present on all requests. Older clients that use x-dell-api-version are still supported, as long as they include a x-dell-api-version request header in the login request, and the client no longer expects x-dell-csrf-token to be present in the login response. Please note that the method of communicating using the old Dell headers is deprecated, and will be removed in a future release.

Authentication and organization selection

Authentication and organization selection

Access to the KACE SMA API is limited to authenticated KACE SMA users. If the appliance is configured for multiple organizations, querying is limited to the currently selected organization for the requesting user.

Authentication and organization selection are available through the KACE SMA Account Management Service. The authentication route is accessed through a POST request at /ams/shared/api/security/login. So for example, if the appliance name is KACE_SMA_Test, the route to login can be: http://KACE_SMA_Test/ams/shared/api/security/login.

The body for the POST request must contain the user name and password, and optionally an organization name. Here is an example body for that request:

When 2FA (multifactor authentication) is enabled, an additional step is required, to supply the security code after obtaining the KACE_CSRF_TOKEN. Failing to do so causes all future API calls to be invalid with an HTTP status of 401, and the following body:

You can supply the 2FA code through a POST request at /ams/shared/api/security/verify_2factor. For example, if the appliance name is KACE_SMA_Test, the route to supply the code is: http://KACE_SMA_Test/ams/shared/api/security/verify_2factor.

The body for the POST request must contain the current code from 2FA. For example:

If the code supplied Google Authenticator is 123456, you can use the following statement:

The header for this request must contain x-kace-api-version.

When a success is received, the custom API call no longer returns the authentication error:

If the security code is valid, the API call returns the HTTP status 200, with the following body:

Once the security code is accepted, all future API calls should function as expected.

Authorization

Authorization

During authentication, the assigned role is retrieved for the given KACE SMA user. This role determines the actions that the user is authorized to perform. With regard to this API, the following default roles have specific capabilities.

If the appliance is updated with custom roles and the current user is assigned one of those roles, its permissions are retrieved. These permission values are used to determine the user’s querying capability for this API. For more information about the KACE SMA roles, see the K1000 Systems Management Appliance Administrator Guide.

Access

Access

The API is available at the K1000 address starting with the path /api.

So for example, if the K1000 name in your environment is K1000Test, the route to the machine entities would be http://K1000Test/api/inventory/machines.