How to Exclude Third-Party Clients During Deployment with AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS

Set AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS to true in your Deploy CLI configuration to automatically filter out Auth0-managed third-party applications from export, import, and change-calculation operations.

The Auth0 Deploy CLI treats every application registered in your tenant as a client, which includes both first-party applications you create and third-party applications provisioned by Auth0 for internal services or marketplaces. When you need to exclude third-party clients during deployment to prevent accidental modifications to Auth0-managed resources, the AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS flag provides a global safety mechanism that filters these clients at both the API request layer and the processing layer.

How the Exclusion Flag Works in the Source Code

The exclusion logic operates through three coordinated layers in the codebase: configuration definition, utility normalization, and handler execution.

Configuration Type Definition

The flag is declared as an optional boolean in the global configuration type definition. In src/types.ts at line 66, the AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS property is typed to accept boolean values that control the filtering behavior across all deployment commands.

Utility Helper Function

Before the flag reaches the business logic, the shouldExcludeThirdPartyClients helper in src/tools/utils.ts (lines 345-354) reads the configuration value and normalizes it. This function accepts both boolean true and string 'true' values, ensuring consistent behavior regardless of whether the setting comes from JSON, YAML, or environment variables.

Client Handler Filtering Logic

The core exclusion logic resides in src/tools/auth0/handlers/clients.ts. At lines 74-81, the filter function removes three categories of clients before processing any changes:

• The management API client itself
• Any client whose name appears in the exclude.clients array
• Third-party clients when the exclusion flag is active, using the logic !shouldExcludeThirdPartyClients(this.config) || item.is_first_party

This ensures that when the flag is enabled, only first-party clients (where is_first_party is true) are eligible for creation, updates, or deletion.

API Pagination Optimization

To improve efficiency and prevent unnecessary data transfer, the exclusion is applied directly at the Auth0 API level. In src/tools/auth0/handlers/clients.ts at lines 24-25, the CLI adds is_first_party: true to the pagination parameters when fetching the current tenant state. When this parameter is present, the Auth0 API returns only first-party clients, meaning third-party clients never enter the "existing" collection used for change calculations.

Configuration and Usage Examples

Enable the flag through your preferred configuration method to activate third-party client exclusion across all operations.

JSON Configuration File

{
  "AUTH0_DOMAIN": "tenant.auth0.com",
  "AUTH0_CLIENT_ID": "your-client-id",
  "AUTH0_CLIENT_SECRET": "your-client-secret",
  "AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS": true
}

Environment Variable

export AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS=true

Export Operation

When exporting your tenant configuration, third-party clients are omitted from the output directory:

npm run build && node lib/index.js export -c config.json -f directory -o ./local/

Import Operation

During import, any third-party clients present in local configuration files are ignored, preventing the CLI from attempting to create, update, or delete Auth0-managed applications:

npm run build && node lib/index.js import -c config.json -i ./local/

Programmatic Usage

If building custom tooling around the Deploy CLI, import the utility helper directly:

import { shouldExcludeThirdPartyClients } from './src/tools/utils';

const config = { AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS: true };

if (shouldExcludeThirdPartyClients(key => config[key])) {
  console.log('Third-party clients will be excluded from this run.');
}

Summary

• The AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS flag is defined as an optional boolean in src/types.ts (line 66) and consumed by the shouldExcludeThirdPartyClients helper in src/tools/utils.ts (lines 345-354).
• When enabled, the client handler in src/tools/auth0/handlers/clients.ts filters out third-party clients using the logic !shouldExcludeThirdPartyClients(this.config) || item.is_first_party (lines 74-81).
• The CLI optimizes API calls by passing is_first_party: true to Auth0's management API (lines 24-25), ensuring third-party clients are never fetched into the state comparison.
• This prevents accidental deletions or modifications to Auth0 internal applications while ensuring your deployment only manages resources you own.

Frequently Asked Questions

What distinguishes a third-party client from a first-party client in Auth0?

A first-party client is any application you create directly in your tenant, such as single-page applications, native apps, or machine-to-machine clients. A third-party client is provisioned automatically by Auth0 for internal services, marketplace integrations, or specific Auth0 features. These appear in your tenant's client list but are managed by Auth0's infrastructure, making them unsafe to modify through deployment tools.

Will enabling AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS delete my existing third-party clients?

No. When the flag is enabled, the Deploy CLI excludes third-party clients from the change calculation entirely. Since the CLI never sees these clients in either the "existing" state (due to the is_first_party: true API filter) or the "desired" state (due to the handler filter), it takes no action on them. Your existing third-party clients remain untouched in the tenant.

Can I exclude specific individual clients while keeping other third-party clients?

Yes. The AUTH0_EXCLUDE_THIRD_PARTY_CLIENTS flag operates globally, but you can target specific clients using the exclude.clients configuration array. In src/tools/auth0/handlers/clients.ts (lines 74-81), the filter checks both the global third-party flag and the specific client exclusion list, allowing you to block individual client names or IDs regardless of their first-party status.

Does this flag affect export operations or only import deployments?

The flag affects all deployment operations consistently. During export, the API pagination filter (lines 24-25) prevents third-party clients from being written to your local configuration files. During import, the handler filter (lines 74-81) ensures any third-party clients accidentally present in local files are ignored. The calculate-changes command also respects the flag, showing diffs only for first-party resources.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}