Authenticate and Interact with a Tenant
To authenticate with a tenant you need to create a tenant API key and use the key to configure an ApiClient
object.
Create a tenant API key
Create an API key for a tenant so that you can use the API to automate tasks on the tenant. You use the primary manager to create the tenant key, so to perform the operation you authenticate with the primary manager. When the tenant key is created, it appears in the Deep Security Manager of the tenant account.
The process to create an API key for a tenant is similar to that for creating an API key for the primary tenant. (See Create an API Key Using Code.)
- Create an ApiKey object and configure the properties.
- Create a TenantsApi object and use it to create the API key on the tenant.
# Create an API key
key = api.ApiKey()
key.key_name = "Temporary Key"
key.role_id = 1
key.locale = "en-US"
key.time_zone = "Asia/Tokyo"
# Generate the secret key for the tenant
tenants_api = deepsecurity.TenantsApi()
generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)
Also see the Generate an API Key for the Tenant operation in the API Reference.
Configure an ApiClient object for a tenant
Configure theApiClient
to use the secret key of the tenant's API key and then send requests to the Deep Security Manager of the tenant. From the secret key, the manager determines which tenant you are targeting.
After you configure the ApiClient, all calls are authenticated using the tenant's API key and the calls target the associated tenant. After you are done interacting with the tenant and you want to make calls to the primary tenant, configure the ApiClient to use an API key for the primary tenant.
tenant_client = api.ApiClient()
tenant_client.configuration = api.Configuration()
tenant_client.configuration.api_key['api-secret-key'] = tenant_key.secret_key
Example: Obtain Intrusion Prevention states of tenant computers
The following example demonstrates how to authenticate and interact with a tenant:
- Creates an API key on the tenant.
- Configures ApiClient to use the tenant API key.
- Obtains the Intrusion Prevention information from each computer that the tenant protects.
- Configures ApiClient to use the API key of the primary tenant.
computer_ip_states = {}
primary_key = configuration.api_key['api-secret-key']
# Create an API key
key = api.ApiKey()
key.key_name = "Temporary API Key"
key.role_id = 1
key.locale = "en-US"
key.time_zone = "Asia/Tokyo"
# Check that the tenant is in the 'active' state
state = api.TenantsApi(api.ApiClient(configuration)).describe_tenant(tenant_id, api_version).tenant_state
if state == 'active':
# Generate the secret key for the tenant
tenants_api = api.TenantsApi(api.ApiClient(configuration))
generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)
# Add the secret key to the configuration
configuration.api_key['api-secret-key'] = generated_key.secret_key
# Include Intrusion Prevention information in the returned Computer objects
expand = api.Expand(api.Expand.intrusion_prevention)
# Get a list of tenant computers
computers_api = api.ComputersApi(api.ApiClient(configuration))
computers_list = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)
# Find the Intrusion Prevention state for each computer
for computer in computers_list.computers:
computer_ip_states[computer.id] = computer.intrusion_prevention.state
# Reset the API key to the primary key
configuration.api_key['api-secret-key'] = primary_key
return computer_ip_states
Example: configure policies for tenants
Create and configure policies for tenants in the same way that you do for the primary Deep Security Manager, except that you use a tenant API key for authentication. The following example creates an API key for a tenant and then uses the key to configure an ApiClient
object. The client interacts with the tenant's Deep Security Manager.
For more information about using the API to work with policies, see Create and Configure Policies.
# Generate the secret key for the tenant
tenants_api = api.TenantsApi(api.ApiClient(configuration))
generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)
# Add the secret key to the configuration
configuration.api_key['api-secret-key'] = generated_key.secret_key
# Add the policy
tenant_policies_api = api.PoliciesApi(api.ApiClient(configuration))
tenant_client_with_policy = tenant_policies_api.create_policy(policy, api_version, overrides=False)
# Reset the API key to the primary key
configuration.api_key['api-secret-key'] = primary_key