Create a Tenant

Create a tenant and configure the runtime aspects of the account. When designing the tenant using the API, use the same background information and guidance that is provided in the Deep Security Help Center.

Synchronous and asynchronous tenant creation

When you create a tenant, you can make an asynchronous (default behavior) or synchronous call.

• Asynchronous: The response is returned immediately when the tenant creation has started. The tenant is in the Created state but it is not yet functional because Deep Security Manager is in the process of creating the tenant database.
• Synchronous: The response is returned when tenant creation is complete. The tenant database is created and the tenant is fully operational. Tenant database creation can require several minutes, depending on server resources.

When tenant creation is complete, the tenant state is either Confirmation Required (the administrator needs to respond to a confirmation email) or Active (no confirmation was required). You are able authenticate and interact with the tenant only when it is active. Therefore, if you create the tenant synchronously with no confirmation required, you can interact with the tenant immediately after you receive the response.

Use an asynchronous call in the following situation:

• You do not need to immediately perform operations on the created tenant
• You want to quickly free up the execution thread

Use a synchronous call in the following situation:

• You need to perform tasks on the tenant immediately after it is created
• You can allow your script to block the execution thread for several minutes

Response object

The response to the tenant creation call includes a Tenant object that represents the new tenant. However, the object that is returned to an asynchronous call contains only a subset of all the tenant properties.

This JSON represents the data structure of a Tenant that is returned for an asynchronous call. The tenantStateis created, and the tenant administrator account is omitted:

{
    "databaseServerID": 0,
    "name": "test tenant",
    "description": "Test tenant created asynchronously",
    "agentInitiatedActivationPassword": "F5240072-399D-8371-B974-BCBA6AB6BCAB",
    "timeZone": "UTC",
    "locale": "en-US",
    "demoMode": false,
    "modulesVisible": [
        "all"
    ],
    "hideUnlicensedModules": true,
    "tenantState": "created",
    "guid": "37DF7B64-FB78-2D83-C074-375D611E2C9C",
    "ID": 2
}

This JSON represents the data structure of a Tenant that is returned for a synchronous call. In the data structure, administrator accounts are associated with the primaryContacts key. In this case, no confirmation from the administrator was required, so the tenantState is active:

{
    "databaseServerID": 0,
    "name": "test tenant 2",
    "description": "Test tenant created synchronously",
    "agentInitiatedActivationPassword": "F91F7E62-1FEC-65E1-F79D-9EC01C365A35",
    "timeZone": "UTC",
    "locale": "en-US",
    "demoMode": false,
    "modulesVisible": [
        "all"
    ],
    "hideUnlicensedModules": true,
    "tenantState": "active",
    "primaryContacts": [
        {
            "username": "MasterAdmin",
            "roleID": 1,
            "emailAddress": "me@example.com",
            "ID": 1
        }
    ],
    "guid": "51D38CD8-F489-CCA5-A304-452DE2F8CC57",
    "ID": 1
}

General steps

Use the following steps to create a tenant:

1. Create an Administrator object with, at a minimum, the user name, password, and email address defined.
2. Create a Tenant object, add the Administrator object, and set the property values that control the runtime aspects of the account:
   • The tenant account name
   • The security modules are visible to them in Deep Security Manager
   • The database server to use (if Deep Security Manager uses multiple databases)
   • Locale and location details
3. Use a TenansApi object to create the tenant on Deep Security Manager. Indicate whether the call is synchronous (it is asynchronous by default), and whether a confirmation email is sent to the administrator.

For example, the following code creates anAdministrator object with the required properties:

admin = api.Administrator()
admin.username = "TenantAdmin"
admin.password = "Pas$w0rd"
admin.email_address = "example@email.com"
admin.receive_notifications = "false"
admin.role_id = 1

const admin = new api.Administrator();
admin.username = "MasterAdmin";
admin.password = "P@55word";
admin.emailAddress = "example@email.com";
tenant.administrator = admin;

Administrator admin = new Administrator();
admin.setUsername("MasterAdmin");
admin.setPassword("P@55word");
admin.setEmailAddress("bad@email.com");

Next, a Tenant object is created and the administrator is added:

tenant = api.Tenant(administrator=admin)

const tenant = new api.Tenant();
tenant.administrator = admin;

Tenant tenant = new Tenant();
tenant.setAdministrator(admin);

You can specify which security modules are visible to the tenant. In this example, the Anti-Malware, Firewall, and Intrusion Prevention modules are made visible:

modules = api.Tenant.modules_visible = ["anti-malware", "firewall", "intrusion-prevention"]
tenant.modules_visible = modules

tenant.modulesVisible = [
  api.Tenant.ModulesVisibleEnum["anti-malware"],
  api.Tenant.ModulesVisibleEnum.firewall,
  api.Tenant.ModulesVisibleEnum["intrusion-prevention"]
];

List<ModulesVisibleEnum> modules = new ArrayList<>();
modules.add(ModulesVisibleEnum.ANTI_MALWARE);
modules.add(ModulesVisibleEnum.FIREWALL);
modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION);

tenant.setModulesVisible(modules);

You must specify the account name and locale:

tenant.name = account_name
tenant.locale = "en-US"

tenant.name = accountName;
tenant.locale = api.Tenant.LocaleEnum["en-US"];

tenant.setName(accountName);
tenant.setLocale(Tenant.LocaleEnum.EN_US);

Finally, create the tenant on Deep Security Manager.

tenants_api = api.TenantsApi(api.ApiClient(configuration))
returned_tenant = tenants_api.create_tenant(tenant, api_version, confirmation_required=False, asynchronous=True)

const tenantsApi = new api.TenantsApi();
return tenantsApi.createTenant(tenant, apiVersion, { confirmationRequired: "false", asynchronous: "true" });

TenantsApi tenantsApi = new TenantsApi();
Boolean confirmationRequired = Boolean.FALSE;
Boolean asynchronous = Boolean.TRUE;
Boolean bypassTenantCache = Boolean.TRUE;
Tenant returnedTenant = tenantsApi.createTenant(tenant, bypassTenantCache, confirmationRequired, asynchronous, apiVersion);

Example

The following example creates the tenant asynchronously and bypasses the tenant cache. Also, an email confirmation is not sent to the administrator so that the tenant is activated as soon as it is in the Active state.

# Define the administrator account
admin = api.Administrator()
admin.username = "TenantAdmin"
admin.password = "Pas$w0rd"
admin.email_address = "example@email.com"
admin.receive_notifications = "false"
admin.role_id = 1

# Create a tenant
tenant = api.Tenant(administrator=admin)

# Set the visible modules
modules = api.Tenant.modules_visible = ["anti-malware", "firewall", "intrusion-prevention"]
tenant.modules_visible = modules

# Set the account name
tenant.name = account_name

# Set the locale and description
tenant.locale = "en-US"
tenant.description = "Test tenant."

# Create the tenant on Deep Security Manager
tenants_api = api.TenantsApi(api.ApiClient(configuration))

return tenants_api.create_tenant(tenant, api_version, confirmation_required=False, asynchronous=True)

// Tenant object
const tenant = new api.Tenant();

// Set the visible modules
tenant.modulesVisible = [
  api.Tenant.ModulesVisibleEnum["anti-malware"],
  api.Tenant.ModulesVisibleEnum.firewall,
  api.Tenant.ModulesVisibleEnum["intrusion-prevention"]
];

// Set the account name
tenant.name = accountName;

// Define the administrator account
const admin = new api.Administrator();
admin.username = "MasterAdmin";
admin.password = "P@55word";
admin.emailAddress = "example@email.com";
tenant.administrator = admin;

// Set the locale and description
tenant.locale = api.Tenant.LocaleEnum["en-US"];
tenant.description = "Test tenant.";

// Creates the tenant
const createTenant = () => {
  const tenantsApi = new api.TenantsApi();
  return tenantsApi.createTenant(tenant, apiVersion, {
    confirmationRequired: "false",
    asynchronous: "true"
  });
};

createTenant()
  .then(newTenant => {
    resolve(newTenant.ID);
  })
  .catch(error => {
    reject(error);
  });

// Create and configure a Tenant object
Tenant tenant = new Tenant();

// Set module visibility
List<ModulesVisibleEnum> modules = new ArrayList<>();
modules.add(ModulesVisibleEnum.ANTI_MALWARE);
modules.add(ModulesVisibleEnum.FIREWALL);
modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION);

// Administrator account
Administrator admin = new Administrator();
admin.setUsername("MasterAdmin");
admin.setPassword("P@55word");
admin.setEmailAddress("bad@email.com");

tenant.setName(accountName);
tenant.setLocale(Tenant.LocaleEnum.EN_US);
tenant.setDescription("Test tenant.");
tenant.setAdministrator(admin);
tenant.setModulesVisible(modules);

// Add the tenant to the manager
TenantsApi tenantsApi = new TenantsApi();
Boolean confirmationRequired = Boolean.FALSE;
Boolean bypassTenantCache = Boolean.TRUE;
Boolean asynchronous = Boolean.TRUE;

return tenantsApi.createTenant(tenant, bypassTenantCache, confirmationRequired, asynchronous, apiVersion);

Also see the Create a Tenant operation in the API Reference. For information about authenticating API calls, see Authenticate with Deep Security Manager.