Skip to main content

OneAPI Configuration

Overview​

OneAPI is Zscaler's unified and secure gateway that provides programmatic access to API resources across various Zscaler services. ZHERO uses OneAPI to perform advanced operations like URL lookups and retrieve additional data that enhances your Zscaler management experience.

Prerequisites​

Before configuring OneAPI in ZHERO:

  1. Zscaler Services Must Be Linked to ZIdentity - Your Zscaler services (ZIA, ZCC) must be linked to your ZIdentity tenant
  2. Required Permissions - You need at least read-only permissions for:
    • Zscaler Internet Access (ZIA)
    • Zscaler Client Connector (ZCC)
  3. ZIdentity Admin Access - You need administrator access to ZIdentity to create API clients

Setting Up OneAPI Client in ZIdentity​

Step 1: Access ZIdentity Admin Portal​

  1. Log in to your ZIdentity Admin Portal
  2. Navigate to Integration > API Clients

Step 2: Create a New API Client​

  1. Click Add API Client

  2. Fill in the following details on the Client tab:

    Client Information:

    • Name: Enter a descriptive name (e.g., "ZHERO Chrome Extension")
    • Description: Enter a purpose description (e.g., "ZHERO Chrome Extension for enhanced Zscaler management")
    • Status: Enable (must be enabled for authentication to work)
    • Access Token Lifetime: Set between 1 minute and 24 hours (recommended: 60 minutes)

    Client Authentication:

    • Select Secret as the authentication method
    • Click Add to generate a client secret
    • Important: Copy and save the generated secret immediately - it won't be displayed again
    • Note the expiry date of the secret (minimum 30 days, maximum 365 days)

Step 3: Configure API Resources​

  1. Select the Resources tab
  2. Select the required API resources:
    • ZIA API - Select with at least read-only role/scope
    • ZCC API - Select with at least read-only role/scope
  3. Click Save

Step 4: Copy Client ID​

After saving:

  1. The system will generate a unique Client ID
  2. Copy and save the Client ID - you'll need it for ZHERO configuration

Configuring OneAPI in ZHERO​

Step 1: Access OneAPI Settings​

  1. Click the ZHERO extension icon in Chrome
  2. Navigate to any Zscaler admin portal where ZHERO is active
  3. Look for the ZHERO floating button (usually top-right corner)
  4. Hover over the floating button and click the settings voice in the menu
  5. Select "OneAPI Credentials" from the menu

Step 2: Enter Your Credentials​

Fill in the form with the following information:

  1. Identity Base URL

    • Format: https://[your-tenant].zslogin.net
    • This is your ZIdentity tenant URL
    • Example: https://acmecorp.zslogin.net

  2. Client ID

    • Paste the Client ID you copied from ZIdentity

  3. Client Secret

    • Paste the Client Secret you saved when creating the API client

  4. Client Secret Expiry Date

    • Select the date when your client secret expires
    • This helps ZHERO remind you to rotate credentials before expiry

  5. ZPA Customer ID (Optional)

    • Only required if you plan to use ZPA-specific features
    • Can be left empty for ZIA-only usage

Step 3: Save and Test​

  1. Click the Save & Test button
  2. ZHERO will:
    • Save your credentials securely
    • Test the connection to OneAPI
    • Display the connection status

Connection Status Indicators​

  • Green Success Message: "Settings saved and connection verified successfully!" - Your OneAPI is properly configured
  • Yellow Warning Message: Settings saved but connection test failed - Check the error details
  • Red Error Message: Failed to save settings - Verify your input

Troubleshooting​

Common Issues​

  1. "Unable to reach the OAuth server" or CORS Error

    • The extension needs permission to access your Identity Base URL
    • Solution: After adding credentials, reload the extension and try again

  2. "Authentication failed" or 401 Error

    • Your Client ID or Client Secret is incorrect
    • Solution: Verify credentials in ZIdentity and re-enter them

  3. "OAuth endpoint not found" or 404 Error

    • Your Identity Base URL is incorrect
    • Solution: Verify the correct URL format for your tenant

  4. "HTML response received" Error

    • Usually indicates an incorrect Identity Base URL
    • Solution: Ensure the URL follows the format https://[tenant].zslogin.net

Credential Rotation​

When your Client Secret is approaching expiry:

  1. Create a new Client Secret in ZIdentity (you can have up to 2 active secrets)
  2. Update the credentials in ZHERO before the old secret expires
  3. Delete the old secret from ZIdentity after confirming the new one works

Security Notes​

  • Credentials are stored securely in Chrome's encrypted storage
  • Credentials are never sent to ZHERO servers
  • All API calls are made directly to Zscaler services
  • OneAPI uses OAuth 2.0 Client Credentials Grant for secure authentication

Further Information​

For detailed information about OneAPI authentication and configuration, refer to the official Zscaler documentation: