# How AUTH0_ALLOW_DELETE Controls Resource Deletion in auth0-deploy-cli

> Learn how AUTH0_ALLOW_DELETE controls resource deletion in auth0-deploy-cli. This global switch enables or blocks permanent removal of Auth0 tenant resources missing from local config.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/types.ts). As part of the `Config` interface, `AUTH0_ALLOW_DELETE` is strictly typed as a boolean value:

```ts
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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:

```ts
// 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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/tools/auth0/handlers/phoneTemplates.ts) implements the following validation pattern:

```ts
// 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`](https://github.com/auth0/auth0-deploy-cli/blob/main/customDomains.ts), [`organizations.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/organizations.ts), [`roles.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/roles.ts), [`scimHandler.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/scimHandler.ts), and the [`default.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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:

```json
// 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:

```bash
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:

```json
{
  "AUTH0_ALLOW_DELETE": false
}

```

In this mode, the CLI outputs warnings similar to:

```text
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/types.ts) that defaults to a safe state when unspecified.
- The **change calculation engine** in [`calculateChanges.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/phoneTemplates.ts), [`customDomains.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/customDomains.ts), and [`organizations.ts`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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.