Contents
Using the Integration Server REST API in multi-tenancy scenarios
Interaction with the Integration Server REST API is based on requests and responses and is carried out over the HTTPS protocol using the multitenancy account.
Account parameters are passed as the following string {username}:{password} at every method call in the Authorization request header and are encoded with the Base64 method. Authentication of the Basic type is used.
The address of the request to the Integration Server REST API consists of the following parts:
https://{Integration Server address}:{Integration Server port}/{method}?{parameters}
where:
{Integration Server address}– IP address or fully qualified domain name (FQDN) of the Integration Server.{Integration Server port}– port for connecting to the Integration Server (port 7271 by default).{method}– method to call.{parameters}– method parameters, if any.
For processing requests that are time consuming and run asynchronously, tasks are used. The task is created as an intermediate query result.
Methods for working with tenants
Using the Integration Server REST API, you can perform the following actions when working with tenants and tenant virtual machines:
- Get information about a tenant
- Get a list of tenants
- Get a list of tenant virtual machines
- Create a new tenant and its protection infrastructure, or register an existing tenant
- remove a tenant
- activate and deactivate a tenant
- register and unregister tenant virtual machines
The set of actions performed as a result of some REST API requests depends on the tenant type that you specify when adding the tenant information to the Integration Server database. Deployment and deletion of the tenant protection infrastructure using the Integration Server REST API is available for complete tenants. For a simple tenant, only report generation is automated.
Getting information about a tenant
Allows you to get information about the tenant from the Integration Server database.
Method:
GET /api/2.0/virtualization/tenants/{tenant ID}
where:
{tenant ID} – tenant identifier in the Integration Server database (required parameter).
In case of successful completion of the request, the REST API returns the following information about the tenant:
<tenant id="{ID}" created="{date and time}" updated="{date and time}">
<name>{name}</name>
<description>{description}</description>
<userData><![CDATA[{additional information}]]></userData>
<!-- Information in the vKsc section is available only for a complete tenant -->
<vKsc id="{ID}">
<user>
<name>{administrator}</name>
</user>
</vKsc>
<status>{status}</status>
<type>{tenant type}</type>
</tenant>
where:
tenant id="{ID}"– tenant identifier in the Integration Server database.created="{date and time}"– date and time when the tenant was registered in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.updated="{date and time}"– date and time when the tenant data was updated in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.{name}– tenant name specified when the tenant was created.{description}– tenant description.{additional information}– additional tenant information added to the Integration Server database.vKsc id="{ID}"– identifier assigned to the tenant's virtual Administration Server in Kaspersky Security Center.{administrator}– name of the administrator of the tenant's virtual Administration Server.{status}– current tenant status:ActiveorInactive.{tenant type}– type of tenant:CompleteorSimple.
Return codes:
200 (OK)– request completed successfully. The tenant information is returned in the response.403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.
Getting a tenant list
Allows you to get a list of all tenants whose information is stored in the Integration Server database, as well as information about each tenant.
Method:
GET /api/2.0/virtualization/tenants
Return codes:
200 (OK)– request completed successfully. A list of information about all tenants is returned in the response.403 (Forbidden)– access to the resource is denied.
Getting a list of tenant virtual machines
Allows you to get a list of all registered tenant virtual machines.
Method:
GET /api/2.0/virtualization/tenants/{tenant ID}/vms
where:
{tenant ID} – tenant identifier in the Integration Server database (required parameter).
If the request succeeds, the REST API returns a list of virtual machines and the following information about each tenant virtual machine:
<vm id="{ID in the database}" biosId={BIOS ID} created="{date and time}" updated="{date and time}">
<name>{name}</name>
<userData><![CDATA[{additional information}]]></userData>
</vm>
where:
{ID in the database}– identifier assigned to the virtual machine in the Integration Server database.{BIOS ID}– virtual machine identifier (BIOS ID) in UUID format.created="{date and time}"– date and time when the virtual machine was registered in the Integration Server database in YYYY-MM-DDThh:mm:ss format.updated="{date and time}"– date and time when the virtual machine data was updated in the Integration Server database in YYYY-MM-DDThh:mm:ss format.{name}– virtual machine name.{additional information}– additional information about the virtual machine stored in the Integration Server database.
Return codes:
200 (OK)– request completed successfully. A list of the tenant virtual machines is returned in the response.403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.
Creating a tenant
Depending on the tenant type that you specify when calling the REST API method, the following actions can be performed:
- For a complete tenant:
- Add tenant data to the Integration Server database.
- Create the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups).
- Add information about the tenant's virtual Administration Server to the Integration Server database.
- For a simple tenant: add the tenant data to the Integration Server database.
Method:
POST /api/2.0/virtualization/tenants
The following parameters must be specified in the request body:
<tenant>
<name>{name}</name>
<description>{description}</description>
<userData><![CDATA[{additional information}]]></userData>
<preferredViisAddress>{IP address}</preferredViisAddress>
<type>{tenant type}</type>
<!-- Data in the vKsc section is specified only for a complete tenant -->
<vKsc>
<user>
<name>{administrator name}</name>
<password>{administrator password}</password>
</user>
</vKsc>
</tenant>
where:
{name}– tenant name (required parameter).{description}– tenant description (optional parameter).{additional information}– additional tenant information (optional parameter).{IP address}– IP address of the Integration Server to which the Light Agents installed on tenant virtual machines will connect (optional parameter). The specified address is used by default when creating the Light Agent policy. If the parameter is not specified, the policy uses the Integration Server IP address from the request to REST API.{tenant type}– type of tenant:CompleteorSimple(optional parameter).{administrator name}– name of the administrator account used to connect to the tenant's virtual Administration Server (required when creating a complete tenant). The account will be created automatically during the procedure.{administrator password}– Base64-encoded password for the administrator account (required when creating a complete tenant).
The request is executed asynchronously, REST API returns identifier of the CreateTenant task. Using the task, you can monitor the progress of the tenant creation procedure. When the task completes, the result field displays information about the tenant including the identifier of the created tenant, or an error message. In case of an error at any step of the procedure, all the changes are rolled back.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the CreateTenant task.400 (Bad request) VIRMT_MandatoryParameterIsNotSpecified– one of the required parameters, for example, the tenant name, is not specified in the request body.400 (Bad request) VIRMT_InvalidTenantType– an invalid tenant type is specified in the request body; the specified tenant type does not exist.400 (Bad request) VIRMT_VKscCredentialsNotSpecified– the name or password of the administrator account of the virtual Kaspersky Security Center Administration Server is not specified (when creating a complete tenant).400 (Bad request) VIRMT_InvalidViisAddressFormat– invalid format of the Integration Server IP address.403 (Forbidden)– access to the resource is denied.
Possible error codes in the task:
KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.VIRMT_TenantGroupAlreadyExists– a folder whose name corresponds to the specified tenant name already exists in Kaspersky Security Center.VIRMT_TenantWithSpecifiedNameAlreadyExists– a tenant with the specified name already exists in the Integration Server database.VIRMT_PasswordNotComplyPolicy– failed to create an administrator account for Kaspersky Security Center virtual Administration Server: the specified password does not meet Kaspersky Security Center password requirements.VIRMT_UserWithSpecifiedNameAlreadyExists– failed to create an administrator account for Kaspersky Security Center virtual Administration Server: a user with the specified name already exists in Kaspersky Security Center.
Activating a tenant
Allows changing the tenant status to "Active".
Method:
POST /api/2.0/virtualization/tenants/{tenant ID}/activate
where:
{tenant ID} – tenant identifier in the Integration Server database (required parameter).
The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.403 (Forbidden)– access to the resource is denied.
Error codes in the task:
VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.
Deactivating a tenant
Allows changing the tenant status to "Inactive".
Method:
POST /api/2.0/virtualization/tenants/{tenant ID}/deactivate
where:
{tenant ID} – tenant identifier in the Integration Server database (required parameter).
The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.403 (Forbidden)– access to the resource is denied.
Error codes in the task:
VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.
Registering tenant virtual machines
Allows you to add information about the tenant virtual machines to the Integration Server database.
Method:
POST /api/2.0/virtualization/tenants/{tenant ID}/vms/register
where:
{tenant ID} – tenant identifier in the Integration Server database (required parameter).
The following parameters must be specified In the request body:
<vm biosId="{BIOS ID}">
<name>{name}</name>
<userData><![CDATA[{additional information}]]></userData>
</vm>
where:
{BIOS ID}– unique virtual machine identifier (BIOS ID) (required parameter).{name}– virtual machine name (optional parameter).{additional information}– additional information about the virtual machine (optional parameter).
Return codes:
200 (OK)– request completed successfully (information about the virtual machine is added to the Integration Server database).403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.409 (Conflict) VIRMT_VmWithSpecifiedBiosIdAlreadyExists– virtual machine with the specified identifier is already registered in the Integration Server database.
Unregistering a virtual machine
Allows you to delete information about the tenant virtual machine from the Integration Server database.
Unregistration does not disable protection of the tenant virtual machine. You can disable protection of the virtual machine for a complete tenant by following all the steps of the procedure for removing virtual machines from the protected infrastructure.
Method:
POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?biosId={ID}
or
POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?vmId={ID}
where:
{tenant ID}– tenant identifier in the Integration Server database (required parameter).biosId={ID}– virtual machine identifier (BIOS ID) in UUID format (required parameter).vmId={ID}– identifier of the virtual machine in the Integration Server database, in the UUID format (required parameter).
Return codes:
200 (OK)– request completed successfully (information about the virtual machine is deleted from the Integration Server database).403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.404 (Not Found) VIRMT_VmWithSpecifiedIdNotFound– virtual machine with the specified identifier is not found in the Integration Server database.
Removing a tenant
Depending on the tenant type and specified parameters, lets you perform the following actions:
- For a complete tenant:
- Delete information about the tenant and tenant virtual machines from the Integration Server database.
- Delete the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups, policies, tasks, and installation packages). If there are no other tenants, the Multitenancy KSV LA folder is also deleted.
- Delete information about the tenant's virtual Administration Server from the Integration Server database.
Calling the tenant removal method does not disable protection on tenant virtual machines. To disable protection, you need to perform all steps of the tenant removal procedure, including removal of Light Agent for Windows, Light Agent for Linux, and Kaspersky Security Center Network Agent from the virtual machines. To suspend protection of the virtual machine for a complete tenant, use the tenant deactivation method.
- For a simple tenant: remove the tenant from the Integration Server database.
Method:
DELETE /api/2.0/virtualization/tenants/{tenant ID}?removeTenantArtifacts={true|false}
where:
{tenant ID}– tenant identifier in the Integration Server database (required parameter).removeTenantArtifacts={true|false}– optional parameter that indicates whether the tenant protection infrastructure must be removed when removing the tenant from the Integration Server database. Possible values:true– when the tenant is removed, the following actions are performed:- Remove the tenant's virtual Administration Server.
- Delete the administrator account of the tenant's virtual Administration Server.
- Delete the Multitenancy KSV LA → <Tenant name> folder and its contents.
- Delete the Multitenancy KSV LA folder if there are no other tenants.
false– the tenant is only deleted from the Integration Server database; the tenant protection infrastructure is not deleted.
The request is executed asynchronously, REST API returns identifier of the DeleteTenant task. You can use the task to monitor the progress of the tenant removal procedure. When the task completes, the result field displays information about the removed tenant or an error message.
In case of an error at any step of the procedure, all the changes are rolled back.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the DeleteTenant task.403 (Forbidden)– access to the resource is denied.
Error codes in the task:
VIRMT_TenantWithSpecifiedIdNotFound– a tenant with the specified identifier is not found in the Integration Server database.KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.
Methods for working with reports
Using the Integration Server REST API, you can perform the following actions when working with tenant protection reports:
- Generate a report
- Upload a report
Report generation
Allows you to generate a report based on data saved to the Integration Server database, taking into account the specified report settings. You can specify the tenant about whose protection you want to generate a report, as well as the time interval for which you want to receive data.
In the header of the Accept request, pass the data output format: Accept:application/csv.
Method:
POST /api/2.0/virtualization/reports/tenants?tenantId={tenant ID}&from={date and time}&to={date and time}
where:
tenantId={tenant ID}– tenant identifier in the Integration Server database. If a tenant is specified, the report includes only information about periods of protection of the virtual machines of this tenant. If a tenant is not specified, the report will include data on all virtual machines that were protected during the specified period.from={date and time}– start date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value is not specified, the date of the earliest record in the Integration Server database is used.to={date and time}– end date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value not specified, the current date is used.
The request is executed asynchronously, REST API returns identifier of the CreateTenantReport task. Using the task, you can monitor the progress of the report generation procedure. When the task execution completes, the result field displays the report identifier or an error message.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the CreateTenantReport task.403 (Forbidden)– access to the resource is denied.404 (Not Found)– a tenant with the specified identifier is not found in the Integration Server database.
Report upload
Allows you to upload a report generated before.
In the header of the Accept request, pass the data output format: Accept: application/csv.
The report can be uploaded in parts. You can specify the data range in the Range request header, for example:
Range: bytes=0-1023
In response to a request with this header, the REST API returns the 206 (Partial content) result and the first kilobyte of data. The response contains the Content-Range and Content-Length headers.
For example:
Content-Range: bytes=0-1023/123456
Content-Length: 1024
Method:
GET /api/2.0/virtualization/reports/tenants/{report ID}
where:
{report ID} – report identifier obtained as a result of successful completion of the CreateTenantReport task (required parameter).
Return codes:
200 (OK)– request completed successfully. The response returns the report data in the format specified in theAcceptheader.206 (Partial content)– request completed successfully. The response returns the part of the report specified by theRangeheading.403 (Forbidden)– access to the resource is denied.404 (Not Found)– report with the specified identifier is not found.415 (Unsupported Media Type)– unsupported format of the requested data (incorrect format was passed in theAcceptrequest header).
Methods for working with tasks
The tasks are used for processing requests that are time consuming and run asynchronously. Task statuses allow you to monitor the progress of actions specified in the request.
A task may have one of the following states:
- Created – task is created but not started.
- Starting – the task is in the process of starting.
- Running – the task is running. For a task in this state, the execution progress is displayed as a percent value.
- Completed – the task has been successfully completed. For a task in this state, the task execution result is displayed. The result contains task-specific data, for example, the identifier of a new tenant after the CreateTenant task completes.
- Stopping – the task is being prepared for completion. If you stopped a task, it may be in this state before switching to the Canceled state.
- Failed – the task failed. For a task in this state, detailed error information is indicated.
- Canceled – the task is terminated by the user or the system. For a task in this state, detailed error information is indicated.
- Queued – the task has been queued and is waiting for execution to start.
By means of the Integration Server REST API, you can perform the following tasks:
- Get a list of tasks
- Get information about a specified task
- Cancel execution of a specified task
Getting task information
Allows you to get information about the task by its identifier.
Method:
GET /api/2.0/virtualization/tasks/{ID}
where:
{ID} – task identifier (required parameter).
In case of successful completion of the request, the REST API returns the following information about the task:
<task id="{ID}" created="{date and time}" stateChanged="{date and time}" changed="{date and time}">
<state>{state}</state>
<type>{type}</type>
<stage>{stage}</stage>
<progress>{execution progress}</progress>
<result>{result}</result>
<!-- If the task execution fails, an error message is displayed instead of the result.
<error>{error message}</error>
</task>
where:
{ID}– task ID.created="{date and time}"– task creation time in YYYY-MM-DDThh:mm:ss format.stateChanged="{date and time}"– time of the task state change in YYYY-MM-DDThh:mm:ss format.changed="{date and time}"– task change time in YYYY-MM-DDThh:mm:ss format.{state}– task state.{type}– task type. For example:CreateTenant– a task that is used in the tenant creation procedure.ChangeTenantActivation– a task that is used in tenant activation and deactivation procedures.DeleteTenant– a task that is used in the tenant deletion procedure.CreateTenantReport– a task that is used in the procedure for generating a tenant protection report.
{name}– task name.{stage}– task execution stage.{execution progress}– the progress of task execution indicated as a percentage.{result}– result of executing the task, for example, information about a created tenant or a report identifier.{error message}– if an error occurs during task execution, an error message is displayed.
Return codes:
200 (OK)– request completed successfully.403 (Forbidden)– access to the resource is denied.404 (Not Found)– task with the specified identifier is not found in the Integration Server database.
Getting a list of tasks
Allows you to get a list of all existing tasks and information about each task in the list.
Method:
GET /api/2.0/virtualization/tasks?createdFrom={date and time}&state={status}&type={type}
where:
createdFrom={date and time}– date and time in YYYY-MM-DDThh:mm:ss format (optional parameter). If the parameter is specified, the list displays the tasks that were created not earlier than the specified date and time.state={state}– task state (optional parameter). If the parameter is specified, the list displays only the tasks with the specified state.type={type}– task type (optional parameter). If the parameter is specified, the list displays only the tasks of the specified type.
Return codes:
200 (OK)– request completed successfully. The response returns a list of tasks.403 (Forbidden)– access to the resource is denied.
Canceling a task
Allows you to stop running tasks. Some tasks cannot be completed immediately. In this case, the 202 (Accepted) code is returned and the task state changes to Stopping.
Method:
POST /api/2.0/virtualization/tasks/{ID}/cancel
where:
{ID} – task identifier (required parameter).
Return codes:
200 (OK)– request completed successfully (the task was canceled).202 (Accepted)– request is accepted for execution (the task state changes to Stopping).403 (Forbidden)– access to the resource is denied.404 (Not Found)– task with the specified identifier is not found.405 (Method Not Allowed)– for child tasks: you can cancel a child task only if you cancel the parent task.409 (Conflict)– the task is already in one of the following states: Cancelled, Failed, Stopped.