How AUTH0_ALLOW_DELETE Controls Resource Deletion in auth0-deploy-cli

The AUTH0_ALLOW_DELETE configuration option acts as a global boolean safety switch that, when set to true, authorizes the auth0-deploy-cli to permanently remove Auth0 tenant resources missing from local configuration files; when false or undefined, it blocks all deletions and emits warnings identifying which resources would have been removed.

The AUTH0_ALLOW_DELETE option is a critical safeguard in the auth0/auth0-deploy-cli repository that prevents accidental data loss during infrastructure synchronization. This boolean flag determines whether the CLI may invoke destructive Management API operations when local configuration files no longer define specific tenant resources. Understanding its implementation across the TypeScript source code helps operators safely manage Auth0 tenant state without risking unintended deletions.

Configuration Schema Definition

The flag is formally declared in the configuration type definition located in src/types.ts. As part of the Config interface, AUTH0_ALLOW_DELETE is strictly typed as a boolean value:

export type Config = {
  …
  AUTH0_ALLOW_DELETE: boolean;
  …
};

This type definition ensures that the configuration parser validates the input as a boolean before any deletion logic executes.

Core Deletion Logic Implementation

The CLI implements deletion controls at two architectural layers: the change calculation engine and the individual resource handlers.

Change Calculation in src/tools/calculateChanges.ts

The central algorithm that determines create, update, and delete operations resides in src/tools/calculateChanges.ts. This module receives the allowDelete parameter derived directly from the AUTH0_ALLOW_DELETE configuration value.

When processing object fields (such as user metadata), the function evaluates whether to mark missing properties for deletion by setting them to null or omitting the operation entirely:

// src/tools/calculateChanges.ts
if (desiredAssetState[fieldName] && Object.keys(desiredAssetState[fieldName]).length) {
  …
  if (desiredAssetState[fieldName][currentObjectFieldPropertyName] === undefined) {
    if (allowDelete) {
      // mark property for deletion (null)
    } else {
      // warn, but do not delete
    }
…
} else if (allowDelete) {
  // entire object field should be emptied → deletion
} else {
  // skip deletion and warn
}

If allowDelete is false, the algorithm skips the creation of null values that would signal the Auth0 Management API to remove properties, effectively preserving existing tenant state regardless of local configuration omissions.

Handler-Level API Guards

Each resource-specific handler contains explicit guards before invoking the Auth0 Management API delete endpoints. For example, src/tools/auth0/handlers/phoneTemplates.ts implements the following validation pattern:

// src/tools/auth0/handlers/phoneTemplates.ts
if (this.config('AUTH0_ALLOW_DELETE') === 'true' ||
    this.config('AUTH0_ALLOW_DELETE') === true) {
  // perform actual delete calls
} else {
  log.warn(`Detected the following phone templates should be deleted …
            You can enable deletes by setting 'AUTH0_ALLOW_DELETE' to true in the config`);
}

This defensive programming pattern appears consistently across handlers including customDomains.ts, organizations.ts, roles.ts, scimHandler.ts, and the default.ts base handler. When the flag evaluates to false, the CLI:

• Skips the DELETE request entirely
• Emits a warning log entry listing the specific assets that would be deleted if the flag were enabled
• Retains the existing resources in the Auth0 tenant

Practical Configuration Examples

Enabling Full Synchronization

To allow the CLI to remove resources that exist in the tenant but are absent from your local configuration, set the flag to true in your configuration file:

// config-prod.json
{
  "AUTH0_DOMAIN": "tenant.auth0.com",
  "AUTH0_CLIENT_ID": "xxx",
  "AUTH0_CLIENT_SECRET": "xxx",
  "AUTH0_ALLOW_DELETE": true
}

Execute the import command to synchronize state:

a0deploy import -c config-prod.json -i ./tenant-config/

Running in Safe Mode (Default)

By omitting the flag or explicitly setting it to false, you enable safe mode where deletions are calculated but not executed:

{
  "AUTH0_ALLOW_DELETE": false
}

In this mode, the CLI outputs warnings similar to:

Detected the following phone templates should be deleted. Doing so may be destructive.
You can enable deletes by setting 'AUTH0_ALLOW_DELETE' to true in the config
{
  "type": "sms",
  "template": "Your verification code is {{code}}"
}

This allows operators to audit the impact before enabling destructive operations.

Summary

• AUTH0_ALLOW_DELETE is a boolean configuration option defined in src/types.ts that defaults to a safe state when unspecified.
• The change calculation engine in calculateChanges.ts uses this flag to decide whether to emit null values or empty objects that trigger API deletions.
• Resource handlers across the codebase (including phoneTemplates.ts, customDomains.ts, and organizations.ts) implement explicit guards that check this flag before invoking Management API delete endpoints.
• When set to false, the CLI preserves tenant resources not present in local configuration and logs warnings for audit purposes.
• When set to true, the CLI performs destructive synchronization, permanently removing resources absent from the local state.

Frequently Asked Questions

What happens if I omit AUTH0_ALLOW_DELETE from my configuration?

If you omit the option or set it to false, the auth0-deploy-cli operates in safe mode. The CLI will identify resources that exist in the Auth0 tenant but are missing from your local configuration files, log warnings indicating which items would be deleted, and skip the actual DELETE API calls. Your tenant retains all existing resources that are not defined locally.

Does AUTH0_ALLOW_DELETE affect all Auth0 resource types uniformly?

Yes, the flag acts as a global control mechanism. According to the source code, handlers for phone templates, custom domains, organizations, roles, and SCIM configurations all implement the same guard pattern checking this.config('AUTH0_ALLOW_DELETE'). However, the specific implementation in calculateChanges.ts handles object field-level deletions (like metadata properties) separately from entire resource deletion, with both paths respecting the flag.

Can I preview deletions without actually removing resources?

While there is no dedicated dry-run flag, setting AUTH0_ALLOW_DELETE to false effectively functions as a preview mode. The CLI calculates all changes and outputs warning logs identifying exactly which resources would be deleted if the flag were enabled. Review these logs to audit the impact before switching the flag to true and re-running the command.

How does AUTH0_ALLOW_DELETE interact with partial object updates?

The flag governs property-level deletions within objects through the logic in src/tools/calculateChanges.ts. When updating an object field like user metadata, if a property exists in the tenant but is undefined in your local configuration, the CLI only sends a null value to clear that specific property when AUTH0_ALLOW_DELETE is true. If false, the CLI preserves the existing property value in the tenant and logs a warning instead of sending the destructive nullification request.

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