Configuring Microtenants Using API

This article provides information for managing Zscaler Private Access (ZPA) Microtenants using APIs. All APIs are rate limited. To learn more, see Understanding Rate Limiting.

The following conditions apply when passing microtenantId, the unique identifier of the Microtenant, in a request:

  • If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained in the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations are limited when you are within a Microtenant.
  • If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant.
  • When making requests using inheritable resources, you can pass microtenantId as null to retrieve data from all Microtenants associated with the tenant.
    • Application Segments
    • Segment Groups
    • App Connectors
    • App Connector Groups
    • Certificates
    • Emergency Access users
    • Machine Groups
    • Microtenants
    • Privileged Approvals
    • Privileged Consoles
    • Privileged Credentials
    • Privileged Portals
    • Provisioning Keys
    • Servers
    • Server Groups
    • ZPA Private Service Edges
    • ZPA Private Service Edge Groups
    Close

Getting Details for All Microtenants

To get details for all Microtenants:

  1. Send a GET request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the endpoint. For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants.
  • {
  "totalPages": "3",
  "list": [
    {
      "id": "72057594038621068",
      "creationTime": "1663791107",
      "modifiedBy": "72057594038052745",
      "name": "Example Microtenant",
      "enabled": false,
      "operator": "OR",
      "criteriaAttribute": "AuthDomain",
      "criteriaAttributeValues": [
        "1467901757270.com"
      ]
    },
    {
      "name": "Default",
      "description": "This is the default Microtenant for users not associated to any Microtenant",
      "enabled": true,
      "operator": "OR"
    }
  ]
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting All Microtenants by Given Filters

To get all Microtenants by the given filters:

  1. Send a POST request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants/search.
  2. Provide the customerId, the tenant ID of the ZPA customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057594037987390/microtenants/search.
  3. Use the following JSON payload to get all Microtenants by given filters.

You choose the filter criteria to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

  • {
     "filterBy": [
       {
         "filterName": "string",
         "operator": "string",
         "values": [
           "string"
         ]
       }
     ],
     "pageBy": {
       "page": "string",
       "pageSize": "string",
       "validPage": 0,
       "validPageSize": 0
     },
     "sortBy": {
       "sortName": "string",
       "sortOrder": "string"
     }
    }
    Close
  • {
      "pageBy":{
         "page":1,
         "pageSize":20
      },
      "filterBy":[
         {
            "filterName":"criteriaAttributeValues",
            "operator":"LIKE",
            "values":[
               "Test"
            ]
         }
      ]
    }
    Close
  • {
     "totalPages": "1",
     "list": [
       {
         "id": "73186051597800497",
         "creationTime": "1669058887",
         "modifiedBy": "73186051597795329",
         "name": "Example Microtenant 1",
         "enabled": true,
         "operator": "OR",
         "criteriaAttribute": "AuthDomain",
         "criteriaAttributeValues": [
           "dummytest-365.in",
           "dummytest.c3.com"
         ]
       },
       {
         "id": "73186051597800358",
         "modifiedTime": "1667566039",
         "creationTime": "1666168946",
         "modifiedBy": "73186051597795329",
         "name": "Example Microtenant 2",
         "enabled": true,
         "operator": "OR",
         "criteriaAttribute": "AuthDomain",
         "criteriaAttributeValues": [
           "dummytestad.com"
         ]
       },
       {
         "id": "73186051597800399",
         "modifiedTime": "1667566034",
         "creationTime": "1666207734",
         "modifiedBy": "73186051597795329",
         "name": "Example Microtenant 3",
         "enabled": true,
         "operator": "OR",
         "criteriaAttribute": "AuthDomain",
         "criteriaAttributeValues": [
           "dummytest.org"
         ]
       },
       {
         "id": "73186051597800513",
         "modifiedTime": "1669223724",
         "modifiedBy": "72057594038052595",
         "name": "Example Test Microtenant",
         "description": "Example Microtenant",
         "enabled": false,
         "operator": "OR",
         "criteriaAttribute": "AuthDomain",
         "criteriaAttributeValues": [
           "dummytest.com",
           "dummytest.co.in"
         ]
       }
     ]
    }
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting Details for a Particular Microtenant

To get details for a particular Microtenant:

  1. Send a GET request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants/{microtenantId}.
  2. Provide the following in the request endpoint:
  • name: The name of the Microtenant.
  • customerId: The ZPA tenant ID of the customer.
  • microtenantId: The Microtenant ID for the particular Microtenant that was captured in the Getting Details for All Microtenants section.

For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants/72057594038621068.

  • {
     "id": "72057594038621068",
     "creationTime": "1663791107",
     "modifiedBy": "72057594038052745",
     "name": "Example Microtenant1",
     "enabled": false,
     "operator": "OR",
     "criteriaAttribute": "AuthDomain",
     "criteriaAttributeValues": [
       "1467901757270.com"
     ]
    }
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Getting Name and ID for All Microtenants

To get the name and ID for all Microtenants:

  1. Send a GET request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants/summary.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants/summary.
  • [
     {
       "id": "72057594038621068",
       "name": "Microtenant1"
     },
     {
       "id": "72057594038622872",
       "name": "security-new"
     },
     {
       "name": "default"
     }
    ]
    Close

A successful response returns code 200. To learn more, see About Error Codes.

Getting Details of User Session and User Microtenant ID

To get details of a user session and a user Microtenant ID, send a GET request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/me.

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.

Creating a Microtenant

The ability to create a Microtenant is only supported for Default Microtenant admins.

To create a Microtenant:

  1. Send a POST request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants.
  3. Use the following JSON payload to update a Microtenant and provide the following information about the Microtenant:
  • name: The name of the Microtenant.
  • criteriaAttribute: The criteria attribute for the Microtenant(i.e., AuthDomain).
  • criteriaAttributeValues: The value for the criteria attribute (i.e., valid authentication domains configured for a customer).

You choose the Microtenant criteria in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

  • {
     "creationTime": 0,
     "criteriaAttribute": "string",
     "criteriaAttributeValues": [
       "string"
     ],
     "description": "string",
     "enabled": true,
     "id": "string",
     "modifiedBy": "string",
     "modifiedTime": 0,
     "name": "string",
     "priority": 0
    }
    Close
  • {
      "name":"Example Microtenant",
      "enabled":false,
      "description":"Example Microtenant",
      "criteriaAttribute":"AuthDomain",
      "criteriaAttributeValues":[
         "dummytest.com",
         "dummytest.co.in"
      ]
    }
    Close
  • {
     "id": "73186051597800513",
     "creationTime": "1669222935",
     "modifiedBy": "72057594038052595",
     "name": "Example Microtenant",
     "description": "Example Microtenant",
     "enabled": false,
     "operator": "OR",
     "criteriaAttribute": "AuthDomain",
     "criteriaAttributeValues": [
       "dummytest.com",
       "dummytest.co.in"
     ],
     "user": {
       "id": "73186051597800514",
       "username": "mtAdmin_73186051597800513@dummytest.com",
       "displayName": "Zscaler Private Access Scope Administrator",
       "email": "mtAdmin_73186051597800513@dummytest.com",
       "password": "#<6I!7WE",
       "roleId": "12",
       "forcePwdChange": true,
       "localLoginDisabled": false,
       "pinSession": true,
       "isLocked": false,
       "microtenantId": "73186051597800513"
     }
    }
    Close

A successful response returns code 201. To learn more, see API Response Codes and Error Messages.

Adding Field Descriptions

The following table includes descriptions of available fields you can use for the Microtenant use cases:

FieldDescriptionRequiredValue
nameThe name of the MicrotenantYesString
enabledWhether the Microtenant is enabled or notNoBoolean: true, false
descriptionThe description of the MicrotenantNoString
criteriaAttributeThe criteria attribute for the MicrotenantYesSupported value: AuthDomain
criteriaAttributeValuesThe value for the criteria attribute. This is the valid authentication domains configured for a customer (e.g., ExampleAuthDomain.com).YesString
filterByThis indicates the filter, the operator, and the value for the filterYesArray of attributes (i.e., filterName, operator, values)
filterNameThe name of the filterYesString
operatorThe operator of the MicrotenantYes

String

Supported values: EQ (Equals), LIKE (Contains), and NQ (Not Equals)

valuesThe values for the filterNoString
pageByThis indicates the page and page sizeNoArray of attributes (i.e., page and pageSize)
pageThis indicates the pageNoInteger
pageSizeThis indicates the page size. If not provided, the default page size is 20. The max page size is 500.NoInteger
sortByThis indicates the sort name and sort orderNoArray of attributes (i.e., sortName and SortOrder)

Updating a Microtenant

The ability to update a Microtenant is only supported for Default Microtenant admins.

To update a Microtenant:

  1. Send a PUT request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants/{microtenantId}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • microtenantId: The Microtenant ID for the particular Microtenant you want to update.

For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants/72057594038621068.

  1. Use the following JSON payload to update a Microtenant and provide the following information about the Microtenant:
  • Name: The name of the Microtenant.
  • criteriaAttribute: The criteria attribute for the Microtenant(i.e., AuthDomain).
  • criteriaAttributeValues: The value for the criteria attribute (i.e., valid authentication domains configured for a customer).
  • {
     "creationTime": 0,
     "criteriaAttribute": "string",
     "criteriaAttributeValues": [
       "string"
     ],
     "description": "string",
     "enabled": true,
     "id": "string",
     "modifiedBy": "string",
     "modifiedTime": 0,
     "name": "string",
     "priority": 0
    }
    Close
  • {
      "name":"Test Microtenant",
      "enabled":false,
      "description":"Example Microtenant",
      "criteriaAttribute":"AuthDomain",
      "criteriaAttributeValues":[
         "dummytest.com",
         "dummytest.co.in"
      ]
    }
    Close

A successful response yields code 204, meaning the Microtenant is updated. To learn more, see API Response Codes and Error Messages.

Deleting a Microtenant

To delete a Microtenant:

  1. Send a DELETE request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/customers/{customerId}/microtenants/{microtenantId}.
  2. Provide the following in the request endpoint:
  • customerId: The ZPA tenant ID of the customer.
  • microtenantId: The Microtenant ID for the particular Microtenant you want to delete.

For example: /mgmtconfig/v1/admin/customers/72057594037927936/microtenants/72057594038621068.

A successful response yields code 204, meaning the Microtenant is deleted. To learn more, see API Response Codes and Error Messages.

Getting the Details of Your Current Session

To get the details of your current session, send a GET request to the following endpoint in the Microtenant controller: /mgmtconfig/v1/admin/me.

  • {
  "customerId": "72057594037927936",
  "customerName": "Zscaler - Example User - safemarch.com",
  "microtenantId": "72057594038621068” 
  "microtenantName": "Example Microtenant"
}
    Close

A successful response returns code 200. To learn more, see API Response Codes and Error Messages.