Skip to main content

Managing Administrator Roles Using API

This article provides information for managing Zscaler Private Access (ZPA) administrator roles using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits.

Getting All Default Permission Groups

To get the details of all default permission groups:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/permissionGroups.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/145256180497776640/permissionGroups.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response​

[
  {
    "id": "9",
    "modifiedTime": "0",
    "creationTime": "1516480235",
    "name": "Administration",
    "hidden": false,
    "internal": false,
    "localScopePermissionGroup": true,
    "classPermissions": [
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "5",
          "modifiedTime": "0",
          "creationTime": "1412894758",
          "aclClass": "com.zscaler.zpath.model.User",
          "friendlyName": "User",
          "localScopeMask": "15"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "1"
        },
        "classType": {
          "id": "14",
          "modifiedTime": "0",
          "creationTime": "1412894758",
          "aclClass": "com.zscaler.common.model.Role",
          "friendlyName": "Role",
          "localScopeMask": "15"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "22",
          "modifiedTime": "0",
          "creationTime": "1412894758",
          "aclClass": "com.zscaler.common.model.Audit",
          "friendlyName": "Audit",
          "localScopeMask": "15"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "85",
          "modifiedTime": "0",
          "creationTime": "1558732428",
          "aclClass": "com.zscaler.zpn.model.UserPortalAUP",
          "friendlyName": "UserPortalAUP",
          "localScopeMask": "15"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "158",
          "modifiedTime": "0",
          "creationTime": "1657523270",
          "aclClass": "com.zscaler.zpn.model.DisasterRecovery",
          "friendlyName": "Disaster Recovery",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "165",
          "modifiedTime": "0",
          "creationTime": "1664780102",
          "aclClass": "com.zscaler.zpn.dto.ZiaCloudConfig",
          "friendlyName": "Zscaler Cloud Sandbox",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "164",
          "modifiedTime": "0",
          "creationTime": "1663835534",
          "aclClass": "com.zscaler.zpn.model.C2cIpRanges",
          "friendlyName": "Client Connector IP Assignement",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "149",
          "modifiedTime": "0",
          "creationTime": "1650354549",
          "aclClass": "com.zscaler.zpn.model.Scope",
          "friendlyName": "Microtenant",
          "localScopeMask": "0"
        }
      }
    ]
  },
  {
    "id": "6",
    "modifiedTime": "0",
    "creationTime": "1516480235",
    "name": "Authentication",
    "hidden": false,
    "internal": false,
    "localScopePermissionGroup": true,
    "classPermissions": [
      {
        "permission": {
          "mask": "1",
          "type": "VIEW_ONLY",
          "maxMask": "15"
        },
        "classType": {
          "id": "86",
          "modifiedTime": "0",
          "creationTime": "1560752143",
          "aclClass": "com.zscaler.common.model.AuthenticationSetting",
          "friendlyName": "AuthenticationSetting",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "133",
          "modifiedTime": "0",
          "creationTime": "1639394078",
          "aclClass": "com.zscaler.zpn.master.model.ZPathConfigOverride",
          "friendlyName": "ZPathConfigOverride",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "37",
          "modifiedTime": "0",
          "creationTime": "1429316165",
          "aclClass": "com.zscaler.zpn.model.Idp",
          "friendlyName": "Idp",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "41",
          "modifiedTime": "0",
          "creationTime": "1429316165",
          "aclClass": "com.zscaler.zpn.model.SamlAttribute",
          "friendlyName": "SamlAttribute",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "1",
          "type": "VIEW_ONLY",
          "maxMask": "15"
        },
        "classType": {
          "id": "72",
          "modifiedTime": "0",
          "creationTime": "1518721867",
          "aclClass": "com.zscaler.common.model.RemoteAssistance",
          "friendlyName": "RemoteAssistance",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "181",
          "modifiedTime": "0",
          "creationTime": "1679041787",
          "aclClass": "com.zscaler.zpn.model.EmergencyAccessConfig",
          "friendlyName": "Emergency Access",
          "localScopeMask": "1"
        }
      },
      {
        "permission": {
          "mask": "15",
          "type": "FULL",
          "maxMask": "15"
        },
        "classType": {
          "id": "182",
          "modifiedTime": "0",
          "creationTime": "1679041787",
          "aclClass": "com.zscaler.zpn.dto.EmergencyAccessUserDTO",
          "friendlyName": "Emergency Access Users",
          "localScopeMask": "15"
        }
      }
    ]
  }
]

Getting Details of a Particular Role

To get details of a particular role:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/roles/{roleId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • roleId: The unique identifier of the role.

    For example: /mgmtconfig/v1/admin/customers/145256180497776640/roles/145256180497776679.

A successful response returns code 200. To learn more, see ZPA API Codes.

{
  "id": 145256180493676679,
  "modifiedTime": 0,
  "creationTime": 1426810977,
  "modifiedBy": 0,
  "name": "Administrator",
  "microtenantId": 0,
  "microtenantName": "example Microtenant",
  "description": "Admin role",
  "bypassAccestorAccessCheck": true,
  "permissions": [
    {
      "id": 0,
      "modifiedTime": 0,
      "creationTime": 0,
      "modifiedBy": 0,
      "permissionMask": 0,
      "classType": {
        "id": 0,
        "modifiedTime": 0,
        "creationTime": 0,
        "modifiedBy": 0,
        "aclClass": "string",
        "friendlyName": "string",
        "localScopeMask": 0,
        "customerId": 0
      },
      "role": "string",
      "customerId": 0
    }
  ],
  "customRole": true,
  "systemRole": true,
  "restrictedRole": true,
  "classPermissionGroups": [
    {
      "id": 0,
      "modifiedTime": 0,
      "creationTime": 0,
      "modifiedBy": 0,
      "name": "string",
      "hidden": true,
      "internal": true,
      "localScopePermissionGroup": true,
      "classPermissions": [
        {
          "modifiedTime": 0,
          "creationTime": 0,
          "modifiedBy": "string",
          "id": "string",
          "permission": {
            "mask": 0,
            "type": "FULL",
            "maxMask": 0
          },
          "classType": {
            "id": 0,
            "modifiedTime": 0,
            "creationTime": 0,
            "modifiedBy": 0,
            "aclClass": "string",
            "friendlyName": "string",
            "localScopeMask": 0,
            "customerId": 0
          }
        }
      ]
    }
  ],
  "users": 0,
  "apiKeys": 0,
  "newAuditMessage": "string",
  "oldAuditMessage": "string"
}

Getting Details of All Configured Roles

To get details of all configured roles:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/roles.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/145256180497776640/roles.

A successful response returns code 200. To learn more, see ZPA API Codes .

Example Response​

[
  {
    "id": "145256180497776679",
    "name": "Plant Manager",
    "description": "Factory Plant Manager",
    "bypassAccestorAccessCheck": false,
    "customRole": true,
    "systemRole": false,
    "restrictedRole": false,
    "classPermissionGroups": [
      {
        "id": "67",
        "modifiedTime": "0",
        "creationTime": "1633072041",
        "name": "Privileged Remote Access",
        "hidden": false,
        "internal": false,
        "localScopePermissionGroup": true,
        "classPermissions": [
          {
            "permission": {
              "mask": "1",
              "type": "VIEW_ONLY",
              "maxMask": "0"
            },
            "classType": {
              "id": "198",
              "modifiedTime": "0",
              "creationTime": "1706108325",
              "aclClass": "com.zscaler.zpn.model.CmdbClusterUpload",
              "friendlyName": "CmdbClusterUpload",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "128",
              "modifiedTime": "0",
              "creationTime": "1632722165",
              "aclClass": "com.zscaler.zpn.model.SRAPortal",
              "friendlyName": "Privileged Portal",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "129",
              "modifiedTime": "0",
              "creationTime": "1632722165",
              "aclClass": "com.zscaler.zpn.model.SRAConsole",
              "friendlyName": "Privileged Console",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "26",
              "modifiedTime": "0",
              "creationTime": "1426810977",
              "aclClass": "com.zscaler.zpn.model.Application",
              "friendlyName": "Application",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "32",
              "modifiedTime": "0",
              "creationTime": "1426810977",
              "aclClass": "com.zscaler.zpn.model.SigningCert",
              "friendlyName": "SigningCert",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "144",
              "modifiedTime": "0",
              "creationTime": "1648565893",
              "aclClass": "com.zscaler.zpn.model.JITApprovalView",
              "friendlyName": "Privileged Approval",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "160",
              "modifiedTime": "0",
              "creationTime": "1660920636",
              "aclClass": "com.zscaler.zpn.model.Credential",
              "friendlyName": "Privileged Credential",
              "localScopeMask": "15"
            }
          },
          {
            "permission": {
              "mask": "15",
              "type": "FULL",
              "maxMask": "0"
            },
            "classType": {
              "id": "268",
              "modifiedTime": "0",
              "creationTime": "1729268777",
              "aclClass": "com.zscaler.zpn.model.CredentialPool",
              "friendlyName": "Privileged Credential Pool",
              "localScopeMask": "15"
            }
          }
        ]
      }
    ],
    "users": "0"
  },
  {
    "id": "145256180497778051",
    "name": "test-disable-ui",
    "bypassAccestorAccessCheck": false,
    "customRole": true,
    "systemRole": false,
    "restrictedRole": false,
    "users": "0"
  },
  {
    "id": "28",
    "name": "API Full Access",
    "description": "API Full Access user with full access to Public APIs",
    "bypassAccestorAccessCheck": false,
    "customRole": false,
    "systemRole": false,
    "restrictedRole": false,
    "apiKeys": "7"
  }
]

Prerequisite API Calls

Before creating or updating a role, you must get the default permission groups.

Creating a New Role

To create a new role:

  1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/roles.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/145256180497776640/roles.
  3. Include the request headers to provide information about the request context:
    • Content-Type: application/json
    • Authorization: Bearer <access_token>
  4. Use the following JSON payload and provide the following information:
    • name: The name of the role.
    • mask: The supported CRUD functions per permission. For multiple functions per permission, add the supported integer values together. For example, for read and delete access, the mask value is 9 (i.e., the sum of 1 and 8). The supported values are:
      • 1: Denotes read-only access
      • 2: Denotes write-only access
      • 4: Denotes create-only access
      • 8: Denotes delete-only access
    • type: The permission type. If the value is set to permission.type value is set to VIEW_ONLY, then the permission.mask value must be set to 1. If the value is set to permission.type value is set to FULL, then the permission.mask value must be set to 15. The supported values are:
      • VIEW_ONLY: Denotes view-only permissions
      • FULL: Denotes full access
    • The default permission groups you want to pass that are captured in Getting All Default Permission Groups.

A successful response returns code 201. To learn more, see ZPA API Codes.

JSON Payload​

 {
  "id": 0,
  "modifiedTime": 0,
  "creationTime": 0,
  "modifiedBy": 0,
  "name": "string",
  "microtenantId": 0,
  "microtenantName": "string",
  "description": "string",
  "bypassRemoteAssistanceCheck": false,
  "permissions": [
    "#/components/schemas/ClassPermission"
  ],
  "customRole": false,
  "systemRole": false,
  "restrictedRole": false,
  "classPermissionGroups": [
    {
      "id": 0,
      "modifiedTime": 0,
      "creationTime": 0,
      "modifiedBy": 0,
      "name": "string",
      "hidden": false,
      "internal": false,
      "localScopePermissionGroup": false,
      "classPermissions": [
        {
          "modifiedTime": 0,
          "creationTime": 0,
          "modifiedBy": "string",
          "id": "string",
          "permission": {
            "mask": 0,
            "type": "FULL",
            "maxMask": 0
          },
          "classType": {
            "id": 0,
            "modifiedTime": 0,
            "creationTime": 0,
            "modifiedBy": 0,
            "aclClass": "string",
            "friendlyName": "string",
            "localScopeMask": 0,
            "customerId": 0
          }
        }
      ]
    }
  ],
  "users": 0,
  "apiKeys": 0,
  "newAuditMessage": "string",
  "oldAuditMessage": "string"
}

Example JSON Payload​

{
   "customRole":false,
   "name":"test aneela apr30",
   "description":"",
   "classPermissionGroups":[
      {
         "id":"82",
         "modifiedTime":"0",
         "creationTime":"1670623256",
         "name":"Browser Isolation",
         "hidden":false,
         "internal":false,
         "localScopePermissionGroup":true,
         "classPermissions":[
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"172",
                  "modifiedTime":"0",
                  "creationTime":"1670623245",
                  "aclClass":"com.zscaler.cbi.zpa.model.CbiBanner",
                  "friendlyName":"CbiBanner",
                  "localScopeMask":"1"
               },
               "key":"BrowserIsolation-com.zscaler.cbi.zpa.model.CbiBanner-172"
            },
            {
               "permission":{
                  "mask":"1",
                  "type":"VIEW_ONLY",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"171",
                  "modifiedTime":"0",
                  "creationTime":"1670623245",
                  "aclClass":"com.zscaler.cbi.zpa.model.CbiCertificate",
                  "friendlyName":"CbiCertificate",
                  "localScopeMask":"1"
               },
               "key":"BrowserIsolation-com.zscaler.cbi.zpa.model.CbiCertificate-171"
            },
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"110",
                  "modifiedTime":"0",
                  "creationTime":"1610745057",
                  "aclClass":"com.zscaler.zpn.model.CbiProfile",
                  "friendlyName":"CbiProfile",
                  "localScopeMask":"15"
               },
               "key":"BrowserIsolation-com.zscaler.zpn.model.CbiProfile-110"
            }
         ],
         "enabled":true,
         "customized":false
      }
   ]
}

Example Response​

 {
  "id": "145256180497790172",
  "modifiedTime": "1746053272",
  "creationTime": "1746053272",
  "modifiedBy": "145256180497790112",
  "name": "test aneela apr30",
  "bypassAccestorAccessCheck": false,
  "customRole": true,
  "systemRole": false,
  "restrictedRole": false,
  "classPermissionGroups": [
    {
      "id": "82",
      "modifiedTime": "0",
      "creationTime": "1670623256",
      "name": "Browser Isolation",
      "hidden": false,
      "internal": false,
      "localScopePermissionGroup": true,
      "classPermissions": [
        {
          "permission": {
            "mask": "15",
            "type": "FULL",
            "maxMask": "15"
          },
          "classType": {
            "id": "172",
            "modifiedTime": "0",
            "creationTime": "1670623245",
            "aclClass": "com.zscaler.cbi.zpa.model.CbiBanner",
            "friendlyName": "CbiBanner",
            "localScopeMask": "1"
          }
        },
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "15"
          },
          "classType": {
            "id": "171",
            "modifiedTime": "0",
            "creationTime": "1670623245",
            "aclClass": "com.zscaler.cbi.zpa.model.CbiCertificate",
            "friendlyName": "CbiCertificate",
            "localScopeMask": "1"
          }
        },
        {
          "permission": {
            "mask": "15",
            "type": "FULL",
            "maxMask": "15"
          },
          "classType": {
            "id": "110",
            "modifiedTime": "0",
            "creationTime": "1610745057",
            "aclClass": "com.zscaler.zpn.model.CbiProfile",
            "friendlyName": "CbiProfile",
            "localScopeMask": "15"
          }
        }
      ]
    },
    {
      "id": "1",
      "modifiedTime": "0",
      "creationTime": "1516480233",
      "name": "CommonGroupWithReadAccess",
      "hidden": true,
      "internal": false,
      "localScopePermissionGroup": false,
      "classPermissions": [
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "1"
          },
          "classType": {
            "id": "70",
            "modifiedTime": "0",
            "creationTime": "1517257732",
            "aclClass": "com.zscaler.common.permission.CommonPermissionReadAccess",
            "friendlyName": "CommonPermissionReadAccess",
            "localScopeMask": "1"
          }
        },
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "1"
          },
          "classType": {
            "id": "185",
            "modifiedTime": "0",
            "creationTime": "1684693390",
            "aclClass": "com.zscaler.zpn.dto.MicrotenantInReadOnlyMode",
            "friendlyName": "MicrotenantInReadOnlyMode",
            "localScopeMask": "15"
          }
        },
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "1"
          },
          "classType": {
            "id": "1",
            "modifiedTime": "0",
            "creationTime": "1412894758",
            "aclClass": "com.zscaler.common.model.Customer",
            "friendlyName": "Customer",
            "localScopeMask": "1"
          }
        },
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "1"
          },
          "classType": {
            "id": "50",
            "modifiedTime": "0",
            "creationTime": "1445388238",
            "aclClass": "com.zscaler.common.service.Zendesk",
            "friendlyName": "Zendesk",
            "localScopeMask": "15"
          }
        },
        {
          "permission": {
            "mask": "1",
            "type": "VIEW_ONLY",
            "maxMask": "1"
          },
          "classType": {
            "id": "111",
            "modifiedTime": "0",
            "creationTime": "1610745057",
            "aclClass": "com.zscaler.zpn.model.ZpnCbiMapping",
            "friendlyName": "ZpnCbiMapping",
            "localScopeMask": "1"
          }
        }
      ]
    },
    {
      "id": "2",
      "modifiedTime": "0",
      "creationTime": "1516480234",
      "name": "CommonGroupWithFullAccess",
      "hidden": true,
      "internal": false,
      "localScopePermissionGroup": false,
      "classPermissions": [
        {
          "permission": {
            "mask": "15",
            "type": "FULL",
            "maxMask": "15"
          },
          "classType": {
            "id": "61",
            "modifiedTime": "0",
            "creationTime": "1484012721",
            "aclClass": "com.zscaler.zpn.model.AdminPreference",
            "friendlyName": "AdminPreference",
            "localScopeMask": "15"
          }
        }
      ]
    },
    {
      "id": "99",
      "modifiedTime": "0",
      "creationTime": "1721110950",
      "name": "ZSDK",
      "hidden": true,
      "internal": false,
      "localScopePermissionGroup": false,
      "classPermissions": [
        {
          "permission": {
            "mask": "15",
            "type": "FULL",
            "maxMask": "15"
          },
          "classType": {
            "id": "240",
            "modifiedTime": "0",
            "creationTime": "1721110895",
            "aclClass": "com.zscaler.zsdk.entity.ZsdkIdentifier",
            "friendlyName": "ZSDK Identifier",
            "localScopeMask": "0"
          }
        },
        {
          "permission": {
            "mask": "15",
            "type": "FULL",
            "maxMask": "15"
          },
          "classType": {
            "id": "282",
            "modifiedTime": "0",
            "creationTime": "1742203028",
            "aclClass": "com.zscaler.zsdk.entity.ZsdkDeviceProfile",
            "friendlyName": "ZSDK Device Posture",
            "localScopeMask": "0"
          }
        }
      ]
    }
  ],
  "newAuditMessage": "{\"name\":\"test aneela apr30\",\"bypassAccestorAccessCheck\":\"false\",\"customRole\":\"true\",\"description\":\"\",\"accessControlGroups\":[{\"id\":82,\"name\":\"Browser Isolation\"},{\"id\":1,\"name\":\"CommonGroupWithReadAccess\"},{\"id\":2,\"name\":\"CommonGroupWithFullAccess\"},{\"id\":99,\"name\":\"ZSDK\"}],\"permissions\":[{\"permissionMask\":15,\"accessType\":\"FULL\",\"classType\":{\"id\":\"240\",\"name\":\"ZSDK Identifier\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"1\",\"name\":\"Customer\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"50\",\"name\":\"Zendesk\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"70\",\"name\":\"CommonPermissionReadAccess\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"185\",\"name\":\"MicrotenantInReadOnlyMode\"}},{\"permissionMask\":15,\"accessType\":\"FULL\",\"classType\":{\"id\":\"282\",\"name\":\"ZSDK Device Posture\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"171\",\"name\":\"CbiCertificate\"}},{\"permissionMask\":15,\"accessType\":\"FULL\",\"classType\":{\"id\":\"172\",\"name\":\"CbiBanner\"}},{\"permissionMask\":15,\"accessType\":\"FULL\",\"classType\":{\"id\":\"61\",\"name\":\"AdminPreference\"}},{\"permissionMask\":15,\"accessType\":\"FULL\",\"classType\":{\"id\":\"110\",\"name\":\"CbiProfile\"}},{\"permissionMask\":1,\"accessType\":\"VIEW_ONLY\",\"classType\":{\"id\":\"111\",\"name\":\"ZpnCbiMapping\"}}]}"
}

Updating a Role

To update a role:

  1. Send a PUT request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/roles/{roleId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • roleId: The unique identifier of the role.

    For example: /mgmtconfig/v1/admin/customers/145256180497776640/roles/145256180497776679.

  3. Include the request headers to provide information about the request context:

    • Content-Type: application/json
    • Authorization: Bearer <access_token>

  4. Use the following JSON payload and provide the following information:

    • name: The name of the role.
    • mask: The supported CRUD functions per permission. For multiple functions per permission, add the supported integer values together. For example, for read and delete access, the mask value is 9 (i.e., the sum of 1 and 8). The supported values are:
      • 1: Denotes read-only access
      • 2: Denotes write-only access
      • 4: Denotes create-only access
      • 8: Denotes delete-only access
    • type: The permission type. If the value is set to permission.type value is set to VIEW_ONLY, then the permission.mask value must be set to 1. If the value is set to permission.type value is set to FULL, then the permission.mask value must be set to 15. The supported values are:
      • VIEW_ONLY: Denotes view-only permissions
      • FULL: Denotes full access
    • The default permission groups you want to pass that are captured in Getting All Default Permission Groups.

A successful response returns code 204, meaning the role is updated. To learn more, see ZPA API Codes.

JSON Payload​

 {
  "id": 0,
  "modifiedTime": 0,
  "creationTime": 0,
  "modifiedBy": 0,
  "name": "string",
  "microtenantId": 0,
  "microtenantName": "string",
  "description": "string",
  "bypassRemoteAssistanceCheck": false,
  "permissions": [
    "#/components/schemas/ClassPermission"
  ],
  "customRole": false,
  "systemRole": false,
  "restrictedRole": false,
  "classPermissionGroups": [
    {
      "id": 0,
      "modifiedTime": 0,
      "creationTime": 0,
      "modifiedBy": 0,
      "name": "string",
      "hidden": false,
      "internal": false,
      "localScopePermissionGroup": false,
      "classPermissions": [
        {
          "permission": {
            "mask": 0,
            "type": "FULL",
            "maxMask": 0
          },
          "classType": {
            "id": 0,
            "modifiedTime": 0,
            "creationTime": 0,
            "modifiedBy": 0,
            "aclClass": "string",
            "friendlyName": "string",
            "localScopeMask": 0,
            "customerId": 0
          }
        }
      ]
    }
  ],
  "users": 0,
  "apiKeys": 0,
  "newAuditMessage": "string",
  "oldAuditMessage": "string"
}

Example JSON Payload​

   "scopeId":0{
   "customRole":false,
   "id":"144118148382064895",
   "objectType":"Role",
   "action":"EDIT",
   "name":"custom",
   "bypassAccestorAccessCheck":false,
   "systemRole":false,
   "restrictedRole":false,
   "classPermissionGroups":[
      {
         "id":"7",
         "modifiedTime":"0",
         "creationTime":"1521771356",
         "name":"Authentication",
         "localScopePermissionGroup":true,
         "classPermissions":[
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"132",
                  "modifiedTime":"0",
                  "creationTime":"1649831030",
                  "aclClass":"com.zscaler.zpn.master.model.ZPathConfigOverride",
                  "friendlyName":"ZPathConfigOverride",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.zpn.master.model.ZPathConfigOverride-132"
            },
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"164",
                  "modifiedTime":"0",
                  "creationTime":"1683993607",
                  "aclClass":"com.zscaler.zpn.model.EmergencyAccessConfig",
                  "friendlyName":"Emergency Access",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.zpn.model.EmergencyAccessConfig-164"
            },
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"165",
                  "modifiedTime":"0",
                  "creationTime":"1683993607",
                  "aclClass":"com.zscaler.zpn.dto.EmergencyAccessUserDTO",
                  "friendlyName":"Emergency Access Users",
                  "localScopeMask":"15"
               },
               "key":"Authentication-com.zscaler.zpn.dto.EmergencyAccessUserDTO-165"
            },
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"37",
                  "modifiedTime":"0",
                  "creationTime":"1429316165",
                  "aclClass":"com.zscaler.zpn.model.Idp",
                  "friendlyName":"Idp",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.zpn.model.Idp-37"
            },
            {
               "permission":{
                  "mask":"1",
                  "type":"VIEW_ONLY",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"72",
                  "modifiedTime":"0",
                  "creationTime":"1521771356",
                  "aclClass":"com.zscaler.common.model.RemoteAssistance",
                  "friendlyName":"RemoteAssistance",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.common.model.RemoteAssistance-72"
            },
            {
               "permission":{
                  "mask":"15",
                  "type":"FULL",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"41",
                  "modifiedTime":"0",
                  "creationTime":"1429316165",
                  "aclClass":"com.zscaler.zpn.model.SamlAttribute",
                  "friendlyName":"SamlAttribute",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.zpn.model.SamlAttribute-41"
            },
            {
               "permission":{
                  "mask":"1",
                  "type":"VIEW_ONLY",
                  "maxMask":"15"
               },
               "classType":{
                  "id":"78",
                  "modifiedTime":"0",
                  "creationTime":"1561880878",
                  "aclClass":"com.zscaler.common.model.AuthenticationSetting",
                  "friendlyName":"AuthenticationSetting",
                  "localScopeMask":"1"
               },
               "key":"Authentication-com.zscaler.common.model.AuthenticationSetting-78"
            }
         ],
         "enabled":true,
         "customized":false,
         "widgetId":"Authentication-7"
      },
      {
         "id":"4",
         "modifiedTime":"0",
         "creationTime":"1521771356",
         "name":"Diagnostics",
         "localScopePermissionGroup":true,
         "classPermissions":[
            {
               "permission":{
                  "mask":"1",
                  "type":"VIEW_ONLY",
                  "maxMask":"1"
               },
               "classType":{
                  "id":"69",
                  "modifiedTime":"0",
                  "creationTime":"1521771356",
                  "aclClass":"com.zscaler.zpn.model.Diagnostics",
                  "friendlyName":"Diagnostics",
                  "localScopeMask":"1"
               },
               "key":"\"Diagnostics-com.zscalerShow more"

Deleting a Role

To delete a role:

  1. Send a DELETE request to the following endpoint:
  2. Send a PUT request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/roles/{roleId}.
  3. Provide the following in the request endpoint:
    • customerId: The ZPA tenant ID of the customer.
    • roleId: The unique identifier of the role.

A successful response returns code 204, meaning the role is deleted. To learn more, see ZPA API Codes.

Adding Field Descriptions

The following table includes available fields you can use for the administrator role API use cases:

FieldDescriptionRequiredValue
classTypeThe details of the permissions resource (e.g., permission name, mask, etc.)Yes
aclClassThe name of the permissionYesString
permission.maskThe supported CRUD functions per permission. For multiple functions per permission, add the supported integer values together. For example, for read and delete access, the mask value is 9 (i.e., the sum of 1 and 8).YesInteger
The supported values are:
  • 1: Denotes read-only access
  • 2: Denotes write-only access
  • 4: Denotes create-only access
  • 8: Denotes delete-only access
permission.typeThe permission type. If the value is set to permission.type value is set to VIEW_ONLY, then the permission.mask value must be set to 1. If the value is set to permission.type value is set to FULL, then the permission.mask value must be set to 15.YesString
The supported values:
  • VIEW_ONLY: Denotes view-only permissions
  • FULL: Denotes full access