Examples: Using the API with Tenant Groups
You can use the Stellar Cyber API to perform the following tasks for tenants:
-
Create a new tenant group
-
Delete an existing tenant group
-
Update an existing tenant group's settings
-
List all tenant groups
-
Retrieve a tenant group's information using its tenant ID
Refer to Configuring API Authentication for general requirements to use the API.
Tenant Group API Syntax
The tenant group API is available at the following location:
https://<DP url>/connect/api/v1/tenant_groups
The table below lists the available methods for the tenants API, along with the corresponding syntax. Following the table, separate sections provide the schema for each method along with a corresponding example.
Task |
Method |
Syntax |
---|---|---|
GET | /tenant_groups | |
GET
|
/tenant_groups/{id} | |
DELETE | /tenant_groups/{id} | |
POST | /tenant_groups/ | |
PATCH | /tenant_groups/{id} |
Get All Tenant Groups
The following example uses cURL with basic authentication to query for all tenant groups with a GET command using the following details:
-
Username:API Key – ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw
-
Stellar Cyber DP IP Address –192.168.11.11
curl -k -u ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET https://192.168.11.11/connect/api/v1/tenant_groups
Values in bold are the values you must supply as part of a similar query.
Get a Specific Tenant Group
The following example uses cURL to query for a specific tenant group with a GET command using the following details:
-
Username:API Key – ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw
-
Stellar Cyber DP IP Address –192.168.11.11
-
Tenant Group ID – 08990563
You can find the tenant group ID in the System | Administration | Tenant Groups page. Click the in the Group ID column and use the Copy to Clipboard command in the context menu that appears to copy the Tenant ID.
curl -k -u ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw -i -H "Accept: application/json" -H "Content-Type: application/json" -X GET https://192.168.11.11/connect/api/v1/tenant_groups/08990563
In response, the API returns configuration details for the specified tenant, similar to the following:
{"data":{"org_id":"default-organization","tenants":["47784549"],"tgrp_id":"08990563","tgrp_logo":"","tgrp_name":"sentinelone","created_at":1612832242,"updated_at":1650927522}}
The "field":"value"
pairs returned by the API are same options you set when creating a tenant group manually in the System | Administration | Tenant Groups page. and are described in the schema in Create a Tenant Group.
Delete a Specific Tenant Group
The following example uses cURL to delete a specific tenant group with a DELETE command using the following details:
-
Username:API Key – ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw
-
Stellar Cyber DP IP Address –192.168.11.11
-
Tenant Group ID – 8f8f3396c7fa444a8f7b8b55e2b75a04
You can find the tenant group ID in the System | Administration | Tenant Groups page. Click the in the ID column and use the Copy to Clipboard command in the context menu that appears to copy the Tenant ID.
curl -k -u ohtani:N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw -i -H "Accept: application/json" -H "Content-Type: application/json" -X DELETE 'https://192.168.11.11/connect/api/v1/tenant_groups/8f8f3396c7fa444a8f7b8b55e2b75a04'
In response, the API returns a success (200 OK
) or failure message.
Deleting a tenant group via the API does not delete the tenant group members themselves. It only deletes the tenant group container. The member tenants still appear in the Tenants page after the group is deleted.
Create a Tenant Group
This section describes how to create a new tenant group in the API. The schema for the tenant groups API lets you specify all of the same configuration details you would when creating a new tenant group in the user interface. The available fields are as follows:
{
"tgrp_name": "string",
"tenants": [
"string"
],
"tgrp_logo": "string"
}
Your call must have the header and the /connect/api/v1/tenant_groups
path. In addition, the following fields are mandatory:
-
tgrp_name – The name of the tenant group to be created
-
tenants – Must include the tenant ID of at least one valid tenant on the server
Sample Update Tenant Group Script
Here is a sample Python script with arguments filled in. Note that any arguments that you don't supply values for are left at their default settings, as described in Using Tenant Groups
#!/usr/bin/env python
import json
import requests
headers={'Accept': 'application/json', 'Content-type': 'application/json'}
elastic_url ='https://192.168.11.11/connect/api/v1/tenant_groups'
json_data = {
"tgrp_name": "Grouped Up",
"tenants": [
"9d1549f33689454bb290d7811d51d321",
"3accb209d68949f1a99b4c27ead50974",
],
}
query = json.dumps(json_data)
response = requests.post(elastic_url, auth=('ohtani','N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw'), data=query, verify=False, headers = headers)
print (response.text)
This example performs a POST call as the user ohtaniwith the API key shown in the text. The call is to the Stellar Cyber server at 192.168.11.11to create a tenant with the following fields:
-
tgrp_name – Grouped Up
-
tenants–
9d1549f33689454bb290d7811d51d321
and3accb209d68949f1a99b4c27ead50974
Tenant IDs can be retrieved from the System | Administration | Tenants page.
All other fields are left at their default values. Here's how the tenant group appears in the user interface after we created it in the API:
Update a Tenant Group
This section describes how update the settings for an existing tenant group. You can use a PATCH to the tenant groups API to change any of the configuration details available when creating a new tenant group in the user interface. The only mandatory fields are the Tenant ID and the Tenant Name (cust_name). The available fields are the same as described in Create a Tenant Group.
Your call must have the header and the /connect/api/v1/tenant_groups/<tenant_group_id>
path, and must have the tgrp_name field, in addition to any optional fields shown in the schema above that you want to change.
Sample Update Tenant Group Script
This script takes the tenant group we created in Create a Tenant Group and adds an additional tenant.
#!/usr/bin/env python
import json
import requests
headers={'Accept': 'application/json', 'Content-type': 'application/json'}
elastic_url ='https://192.168.11.11/connect/api/v1/tenant_groups/aa57276476b9434b88a512d600a915dd'
json_data = {
"tgrp_name": "Grouped Up",
"tenants": [
"294df931be1f436c8de7d0b106cc0b9f",
"9d1549f33689454bb290d7811d51d321",
"3accb209d68949f1a99b4c27ead50974",
],
}
query = json.dumps(json_data)
response = requests.patch(elastic_url, auth=('ohtani','N-YrP02Xl6yHO-1HW1gi1nems2g319Q3wLNpOAxWx9_ttbMw3pyB5qPvSVl3qt9CmgvOhHhtDCuEs5KcIn6mWw'), data=query, verify=False, headers = headers)
print (response.text)
This example performs a PATCH as the user ohtaniwith the API key shown in the text. The call is to the Stellar Cyber server at 192.168.11.11to add an additional tenant to the group:
-
Tenant Group ID –
aa57276476b9434b88a512d600a915dd
The Tenant ID can be retrieved from the System | Administration | Tenants page and included in the URL.
-
tgrp_name – Grouped Up
-
tenants–
-
294df931be1f436c8de7d0b106cc0b9f
-
9d1549f33689454bb290d7811d51d321
-
3accb209d68949f1a99b4c27ead50974
-
Note that our update script included both the existing tenants in the group and the one we wanted to add. If we'd just included the new tenant, the other two would have been removed from the group. Here's how our tenant group looks after the update: