An API role defines a client application's permission and access to the different API categories in the Zscaler cloud service API. An API role is not assigned to an admin. Instead, it is used during the configuration of an external OAuth 2.0 authentication server for API authentication.

Configuring an API role is one of the tasks you must complete when configuring an external OAuth 2.0 authentication server for API authentication. To learn more, see Securing ZIA APIs with OAuth 2.0.

You can add up to 16 API roles. For a complete list of ranges and limits per feature, see Ranges & Limitations.

Prerequisites

To configure API roles, the admin must be assigned to a role that has full permission to Administrators Access in the ZIA Admin Portal. To learn more, see Adding Admin Roles.

Admin rank doesn't apply to API roles.

Adding API Roles

To configure API roles:

1. Go to Administration > Role Management.

2. Click Add API Role.

   See image.

   Close

   The Add API Role window appears.

3. In the Add API Role window:
   • Name: Enter a name for the API role.
   • Permissions: Permissions allow you to control a client application's access to the major API categories of the cloud service API. For each API role, you must select permissions in the following categories:
     • Policy Access

       The client application can configure, view, and export policies and associated settings using the different API categories in the cloud service API. If you give the role Full or View Only permission to Policy Access, you can specify which API categories the client application can configure or view by enabling a specific Functional Scope. However, functional scope has no control over the API categories used for Administrators Access.

       Choose one of the following permissions:

       • Full: Allows the client application full access to the API categories that you enable in the Functional Scope section of the window.
       • View Only: Allows the client application view only access to the API categories that you enable in the Functional Scope section of the window.
       • None: Doesn't allow the client application access to the API categories.

       Close
     • Administrators Access

       The client application can add other admins, create roles, and view audit logs using a couple of different API categories in the cloud service API.

       Choose one of the following permissions:

       • Full: Allows the client application full access to the following API categories:
         • Admin & Role Management
         • Admin Audit Logs
       • View Only: Allows the client application view only access to the following API categories:
         • Admin & Role Management
         • Admin Audit Logs
       • None: Doesn’t allow the client application access to the following API categories:
         • Admin & Role Management
         • Admin Audit Logs

       Close
   • Functional Scope: Select which categories of APIs the client application can access. If an API role has Full or View Only permission to Policy Access, you can specify with more granularity which API categories the client application can access within the cloud service API. Functional scopes you can enable or disable include:
     • Advanced Settings

       Enable to allow the client application access to the User Authentication Settings API category and the /authSettings/exemptedUrls sub-category within the cloud service API.

       Close
     • Data Loss Prevention

       Enable to allow the client application access to the Data Loss Prevention API category and the following sub-categories within the cloud service API:

       • /dlpDictionaries
       • /dlpEngines
       • /dlpExactDataMatchSchemas
       • /dlpNotificationTemplates
       • /idmprofile
       • /webDlpRules

       Close
     • Security

       Enable to allow the client application access to the Security Policy Settings API category within the cloud service API.

       Close
     • SSL Policy

       Enable to allow the client application access to the following API categories and sub-categories with the cloud service API:

       • SSL Inspection Settings API category
       • Firewall Policies API category and the /ipDestinationGroups sub-category

       Close
     • Firewall, DNAT, DNS & IPS

       Enable to allow the client application access to the Firewall Policies API category and the following sub-categories within the cloud service API:

       • /ipDestinationGroups
       • /ipSourceGroups
       • /networkApplications
       • /networkApplicationGroups
       • /networkService
       • /networkServiceGroups
       • /firewallFilteringRules

       Close
     • Access Control (Web and Mobile)

       You can specify at a more granular level the client applications access to the different API categories for the Access Control (Web and Mobile) functional scope.

       • Policy and Resource Management

         Enable to allow the client application access to the following API categories and sub-categories within the cloud service API:

         • Shadow IT Report category
         • URL Filtering Policies API category
         • URL Categories API category
           • /urlCategories (GET) sub-category
           • /urlCategories (PUT) sub-category (Predefined category)

         Close
       • Custom URL Category Management

         Enable to allow the client application access to the URL Categories API category and the following sub-categories within the cloud service API:

         • /urlCategories (GET) sub-category
         • /urlCategories (POST/DELETE) sub-category
         • /urlCategories (PUT) sub-category (Custom category)

         Close
       • Override Existing Categories

         Enable to allow the client application access to the URL Categories API category and the following sub-categories within the cloud service API:

         • /urlCategories (GET) sub-category
         • /urlCategories (POST/DELETE) sub-category
         • /urlCategories (PUT) sub-category

         Close

       Close
     • Traffic Forwarding

       You can specify at a more granular level the client applications access to the different API categories for the Traffic Forwarding functional scope.

       • Locations

         Enable to allow the client application access to the Location Management API category and the /extranet sub-category within the cloud service API.

         Close
       • VPN Credentials

         Enable to allow the client application access to the Traffic Forwarding API category and /vpnCredentials and /extranet sub-categories within the cloud service API.

         Close
       • Static IPs

         Enable to allow the client application access to the Traffic Forwarding API category and the /staticIP and /region sub-categories within the cloud service API.

         Close
       • GRE Tunnels

         Enable to allow the client application access to the Traffic Forwarding API category and the following sub-categories within the cloud service API:

         • /greTunnels
         • /vips/recommendedList

         Close

       Close
     • Authentication Configuration

       Enable User Management to allow the client application access to the User Management API category within the cloud service API.

       Close

Functional scope has no control over the Administrators Access category. The Administrators Access permission above determines the client application's access to the API categories for administrator control.

See image.

4. Click Save and activate the change.

The API role is created and an internal API user is automatically created for the role in the format of oauth-<rolename>$@<orgid>.<cloud_domain>. For example, oauth-apirole1$@64444.zscaler.net is used as the User context in any API operation. It is also displayed in the audit log for any API operation that is authenticated by an external OAuth 2.0 authentication server. However, this internal user is not displayed on the Administrator Management or User Management pages in the ZIA Admin Portal.

After the API role is created, define that role as a Scope on the authorization server. You must configure the Scope value in the <Zscaler Cloud Name>::<Org ID>::<API Role> format, where:

• Zscaler Cloud Name represents the cloud on which your organization is provisioned.
• Org ID represents your organization ID obtained from the ZIA Admin Portal (under Administration > Company Profile).
• API Role represents an API role configured in the Add API Role window in the ZIA Admin Portal.

You can edit or delete API roles at any time.