Configuring Privileged Portals Using API

This article provides information on managing Zscaler Private Access (ZPA) privileged portals using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits and About Privileged Portals.

Creating a New Privileged Portal

To create a new privileged portal for a given customer using an existing certificate:

1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal.

2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: mgmtconfig/v1/admin/customers/289370814522851328/praPortal

3. Include the request headers to specify the following parameters about the request context:

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

4. Use the following JSON payload and provide the following in the request body:

   • The name of the privileged portal
   • The unique identifier of the certificate
   • The domain of the privileged portal

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

JSON Payload

{
  "certificateId":0,
  "domain":"string",
  "enabled":true,
  "name":"string",
  "userNotificationEnabled":false
}

Example JSON Payload

{
  "enabled":true,
  "name":"testPortal12",
  "domain":"testPortal12",
  "userNotificationEnabled":false,
  "certificateId":"289370814522851367"
}

Example Response

{
  "id":"289370814523661112",
  "modifiedTime":"1684403355",
  "creationTime":"1684403355",
  "modifiedBy":"145256180497777000",
  "name":"testPortal12",
  "enabled":true,
  "certificateId":"289370814522851367",
  "domain":"testportal12",
  "userNotificationEnabled":false
}

Zscaler-Managed Portal Certificate

To create a new privileged portal for a given customer using a portal certificate that is managed by Zscaler:

1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal.
2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: mgmtconfig/v1/admin/customers/289370814522851328/praPortal
3. Include the request headers to specify the following parameters about the request context:
   • Content-Type: application/json
   • Authorization: Bearer <access_token>
4. Use the following JSON payload and provide the following in the request body:
   • name: The name of the privileged portal.
   • userPortalGid: The unique identifier of the user portal. The userPortalGid is only required if you publish links from a user portal in a Privileged Remote Access privileged portal to provide a unified end user experience. For managed Browser Access and DNS, the userPortalGid value can be empty. To learn more, see Configuring User Portals Using API.
   • userPortalName: The name of the user portal.
   • extLabel: The authentication domain name prefix used for the portal URL. The supported string can include integers, lowercase characters, and hyphens (-). This field supports integers between 3 and 31 (e.g., server-2). This field is only required when configuring a portal that uses a certificate managed by Zscaler.
   • extDomain: The authentication domain name prefix used for Zscaler-managed certificates when creating a privileged portal. This field is returned when making GET requests to retrieve application segment details. If you are using Zscaler-managed certificates and pass the external domain name prefix, the certificateId field becomes null. Periods (.) are not supported since the FQDN includes a period as part of the suffix or top-level domain.

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

JSON Payload

{
  "enabled": true,
  "name": "<name>",
  "description": "<description>",
  "userNotificationEnabled": false,
  "userNotification": "<string>",
  "isSRAPortal": true,
  "userPortalGid": "<user portal ID>",
  "userPortalName": "<user portal name>",
  "extLabel": "<external authentication domain name prefix>",
  "extDomain": "<external authentication domain name prefix>"
}

Example JSON Payload

{
   "enabled":true,
   "name":"Example Portal",
   "certManagedByZsRadio":"managed",
   "description":"Example description",
   "userNotificationEnabled":false,
   "userNotification":"",
   "isSRAPortal":true,
   "userPortalGid":"73223709871674468",
   "userPortalName":"sampleUserPortalConfig",
   "extLabel":"server-2",
   "extDomain":"mynewauto.com"
}

Example Response

{
   "id":"73223709871674470",
   "modifiedTime":"1744826831",
   "creationTime":"1744826831",
   "modifiedBy":"72057594038040687",
   "name":"Example Portal",
   "enabled":true,
   "description":"Example description",
   "domain":"server-2-mynewauto-com.pra.d.zscalerportal.net",
   "userNotificationEnabled":false,
   "userPortalGid":"73223709871674468",
   "extLabel":"server-2",
   "extDomainTranslation":"mynewauto.com",
   "extDomain":"mynewauto.com",
   "userPortalName":"sampleUserPortalConfig"
}

Microtenant Support

To create a privileged portal in a Microtenant:

1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/praPortal?microtenantId=145260601092866314

3. Include the request headers to specify the following parameters about the request context:

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

4. Use the following JSON payload and provide the following in the request body:

   • The name of the privileged portal
   • The unique identifier of the certificate
   • The domain of the privileged portal

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

JSON Payload

{
  "certificateId":0,
  "domain":"string",
  "enabled":true,
  "name":"string",
  "userNotificationEnabled":false
}

Example JSON Payload

{
  "enabled":true,
  "name":"testPortal12",
  "domain":"testPortal12",
  "userNotificationEnabled":false,
  "certificateId":"289370814522851367"
}

Example Response

{
  "id":"145260601092866514",
  "modifiedTime":"1704924637",
  "creationTime":"1704924637",
  "modifiedBy":"145260601092866482",
  "name":"public-api",
  "enabled":true,
  "certificateId":"145260601092866074",
  "domain":"public-api.com",
  "userNotificationEnabled":false,
  "microtenantId":"145260601092866314"
}

Getting Details of All Privileged Portals

To get all privileged portals that are configured for a customer:

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

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

Example Response

{
  "totalPages":"1",
  "totalCount": "2",
  "list":[
     {
        "id":"217246660303026030",
        "creationTime":"1642122047",
        "modifiedBy":"72057594038008981",
        "name":"TestPriviledgePortal",
        "enabled":true,
        "description":"Priviledge Portal",
        "certificateId":"217246660303022046",
        "certificateName":"CN=*.mockcompany.com,O=Zscaler,ST=California,C=US",
        "cName":"217246660303026030.217246660302995456.pra.d.zpa-app.net",
        "domain":"Testpriviledgeportal.com",
        "userNotificationEnabled":false
     },
     {
        "id":"217246660303026391",
        "modifiedTime":"1652836201",
        "creationTime":"1652836184",
        "modifiedBy":"72057594038071293",
        "name":"TestPRAExporter1",
        "enabled":true,
        "certificateId":"217246660303022046",
        "certificateName":"CN=*.mockcompany.com,O=Zscaler,ST=California,C=US",
        "cName":"217246660303026391.217246660302995456.pra.d.zpa-app.net",
        "domain":"Testpraexp1.com",
        "userNotificationEnabled":false
     },
     {
        "id":"217246660303026335",
        "modifiedTime":"1652836155",
        "creationTime":"1650420269",
        "modifiedBy":"72057594038071293",
        "name":"TestPRAExporter2",
        "enabled":true,
        "certificateId":"217246660303022046",
        "certificateName":"CN=*.mockcompany.com,O=Zscaler,ST=California,C=US",
        "cName":"217246660303026335.217246660302995456.pra.d.zpa-app.net",
        "domain":"Testpraexp2.com",
        "userNotificationEnabled":false
     }
  ]
}

Pagination

This API supports pagination. To get a paginated response:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal?page=1&pagesize=20.
2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/praPortal?page=1&pagesize=2

NOTE

If not provided, the default page size is 20. The maximum page size is 500.

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

Example Response

{
  "totalPages":"2",
  "totalCount": "4",
  "list":[
     {
        "id":"217246660303026030",
        "creationTime":"1642122047",
        "modifiedBy":"72057594038008981",
        "name":"TestPriviledgePortal",
        "enabled":true,
        "description":"Priviledge Portal",
        "certificateId":"217246660303022046",
        "certificateName":"CN=*.mockcompany.com,O=Zscaler,ST=California,C=US",
        "cName":"217246660303026030.217246660302995456.pra.d.zpa-app.net",
        "domain":"Testpriviledgeportal.com",
        "userNotificationEnabled":false
     },
     {
        "id":"217246660303026391",
        "modifiedTime":"1652836201",
        "creationTime":"1652836184",
        "modifiedBy":"72057594038071293",
        "name":"TestPRAExporter1",
        "enabled":true,
        "certificateId":"217246660303022046",
        "certificateName":"CN=*.mockcompany.com,O=Zscaler,ST=California,C=US",
        "cName":"217246660303026391.217246660302995456.pra.d.zpa-app.net",
        "domain":"Testpraexp1.com",
        "userNotificationEnabled":false
     }
  ]
}

Microtenant Support

This API supports Microtenants. To get details of all privileged portals within a Microtenant:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: mgmtconfig/v1/admin/customers/145260601092866048/praPortal?microtenantId=145260601092866314

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

Example Response

{
   "totalPages":"1",
   "totalCount":"2",
   "list":[
      {
         "id":"145260601092866113",
         "modifiedTime":"1702537630",
         "creationTime":"1693202870",
         "modifiedBy":"72057594038073668",
         "name":"OT Example Default Portal",
         "enabled":true,
         "description":"Hello!",
         "certificateId":"145260601092866074",
         "certificateName":"pra-portal-example.com",
         "cName":"145260601092866113.145260601092866048.pra.d.zpa-app.net",
         "domain":"pra-portal-otdev.com",
         "userNotification":"TEST",
         "userNotificationEnabled":true,
         "microtenantName":"Default"
      },
      {
         "id":"145260601092866325",
         "modifiedTime":"1698124586",
         "creationTime":"1698124586",
         "modifiedBy":"72057594038068982",
         "name":"Scope C Portal",
         "enabled":true,
         "certificateId":"145260601092866074",
         "certificateName":"pra-portal-example.com",
         "cName":"145260601092866325.145260601092866048.pra.d.zpa-app.net",
         "domain":"pra-portal-sample-scope-c.com",
         "userNotificationEnabled":false,
         "microtenantId":"145260601092866314",
         "microtenantName":"Scope C"
      }
   ]
}

Getting Details of a Particular Privileged Portal

To get the details of a particular privileged portal for a given customer:

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

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • id: The unique identifier of the privileged portal. To learn more, see Getting Details of All Privileged Portals.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/praPortal/289370814522851328

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

Example Response

{
  "id":"289370814522851641",
  "creationTime":"1668688130",
  "modifiedBy":"72057594038624153",
  "name":"kritest",
  "enabled":true,
  "description":"Sample portal",
  "certificateId":"289370814522851367",
  "certificateName":"portaltest",
  "cName":"289370814522851641.289370814522851328.h.d.zpa-app.net",
  "domain":"kritest.com",
  "userNotificationEnabled":false
}

Microtenant Support

This API supports Microtenants. To get details of a particular privileged portal within a Microtenant:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal/{id}?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • microtenantId: The unique identifier of the Microtenant for the tenant. To learn more, see Configuring Microtenants Using API.

   For example: mgmtconfig/v1/admin/customers/145260601092866048/praPortal/145260601092866514?microtenantId=145260601092866314

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

Example Response

{
   "id":"145260601092866514",
   "modifiedTime":"1704924637",
   "creationTime":"1704924637",
   "modifiedBy":"145260601092866482",
   "name":"public-api",
   "enabled":true,
   "certificateId":"145260601092866074",
   "certificateName":"pra-portal-sample.com",
   "cName":"145260601092866514.145260601092866048.pra.d.zpa-app.net",
   "domain":"public-api.com",
   "userNotificationEnabled":false,
   "microtenantId":"145260601092866314",
   "microtenantName":"Scope C"
}

Updating a Privileged Portal

To update a privileged portal:

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

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • id: The unique identifier of the privileged portal.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/praPortal/289370814523661112

3. Include the request headers to specify the following parameters about the request context:

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

4. Use the following JSON payload and provide the following in the request body:

   • The name of the privileged portal
   • The unique identifier of the certificate
   • The domain of the privileged portal

A successful response returns code 204, meaning the update was successful. To learn more, see ZPA API Codes.

JSON Payload

{
  "certificateId":0,
  "domain":"string",
  "enabled":true,
  "name":"string",
  "userNotificationEnabled":true
}

Example JSON Payload

{
  "name":"testPortal123",
  "enabled":true,
  "certificateId":"289370814522851367",
  "domain":"testportal12",
  "userNotificationEnabled":false
}

Microtenant Support

This API supports Microtenants. To update a privileged portal within a Microtenant:

1. Send a PUT request to the following endpoint within the Privileged Portal Controller: /mgmtconfig/v1/admin/customers/{customerId}/praPortal/{id}?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/praPortal/289370814523661112?microtenantId=145260601092866314

3. Include the request headers to specify the following parameters about the request context:

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

4. Use the following JSON payload and provide the following in the request body:

   • The name of the privileged portal
   • The unique identifier of the certificate
   • The domain of the privileged portal

A successful response returns code 204, meaning the update was successful. To learn more, see ZPA API Codes.

Minimum Criteria JSON Payload

{
   "certificateId":0,
   "domain":"string",
   "enabled":true,
   "name":"string",
   "userNotificationEnabled":true
}

Example JSON Payload

{
   "enabled":true,
   "name":"public-api-edit",
   "domain":"public-api.com",
   "userNotificationEnabled":false,
   "certificateId":"145260601092866074"
}

Deleting a Privileged Portal

To delete a privileged portal:

1. Send a DELETE request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal/{id}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • id: The unique identifier of the privileged portal.

   For example: mgmtconfig/v1/admin/customers/289370814522851328/praPortal/289370814523661112

A successful response returns code 204, meaning the privileged portal was deleted. To learn more, see ZPA API Codes.

This API supports Microtenants. To delete a privileged portal within a Microtenant:

1. Send a DELETE request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/praPortal/{id}?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: mgmtconfig/v1/admin/customers/289370814522851328/praPortal/289370814522851641?microtenantId=145260601092866314

A successful response returns code 204, meaning the privileged portal was deleted. To learn more, see ZPA API Codes.

Field Descriptions

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

Field	Description	Required	Value
customerId	The unique identifier of the ZPA tenant	Yes	Integer
page	Specifies the page number	No	Integer
pageSize	Specifies the page size	No	Integer
search	Indicates the search string used to support search by features or fields	No	String
microtenantId	The unique identifier of the Microtenant for the ZPA tenant. 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. Pass microtenantId as null to retrieve data from all customers associated with the tenant. If the microtenantId is not passed in the request endpoint when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.	No	Integer
userPortalGid	The unique identifier of the user portal. This field is only required if you publish links from a user portal in a PRA privileged portal to provide a unified end user experience. For managed Browser Access and DNS, the value for this field can be empty. To learn more, see Configuring User Portals Using API.	No	Integer
userPortalName	The name of the user portal	No	String
extLabel	The authentication domain name prefix used for the privileged portal URL. This field is only required when configuring a portal that uses a certificate managed by Zscaler.	No	String and integer The supported string can include integers, lowercase characters, and hyphens (-). This field supports integers between 3 and 31 (e.g., server-2).
extDomain	The authentication domain name prefix used for a Zscaler-managed certificate when creating a privileged portal. This field is returned when making GET requests to retrieve application segment details. If you are using Zscaler-managed certificates and pass the external domain name prefix, the certificateId field becomes null.	No	String and integer Periods (.) are not supported since the FQDN includes a period as part of the suffix or top-level domain.