How AUTH0_EXPORT_IDENTIFIERS Controls Resource Identifier Export in Auth0 Deploy CLI

Setting AUTH0_EXPORT_IDENTIFIERS=true includes Auth0-generated resource IDs in exported configuration files, while the default false value strips these identifiers to produce clean, tenant-agnostic assets.

The AUTH0_EXPORT_IDENTIFIERS configuration flag in the auth0-deploy-cli repository governs whether Auth0-assigned identifiers persist in your exported tenant configurations. This boolean setting directly impacts how portable your configuration files are across different Auth0 tenants and determines whether you can achieve deterministic round-trip exports and imports.

What Is AUTH0_EXPORT_IDENTIFIERS?

AUTH0_EXPORT_IDENTIFIERS is a global boolean configuration option that controls the inclusion of system-generated identifiers—such as id and client_id fields—when exporting Auth0 resources.

• When set to true, the exported JSON or YAML files retain the original Auth0 identifiers, enabling perfect round-trip fidelity but making the files tenant-specific.
• When set to false (the default), these identifiers are omitted, leaving only mutable attributes like names and descriptions, which creates environment-agnostic configuration files suitable for cross-tenant deployments.

Configuration Definition and Type Safety

The flag is formally defined in the global configuration interface within the auth0-deploy-cli source code. In src/types.ts, the Config interface declares the optional boolean property:

export interface Config {
  // …
  AUTH0_EXPORT_IDENTIFIERS?: boolean;
}

Every export context—whether YAML or directory-based—receives this configuration object. Resource handlers across the codebase consult this flag to determine whether to include identifier fields in their output.

Implementation in YAML Export Handlers

The auth0-deploy-cli applies conditional logic in each resource handler to check the flag status. For example, in src/context/yaml/handlers/actions.ts, the handler evaluates the configuration before constructing the export object:

const includeIdentifiers = Boolean(context.config.AUTH0_EXPORT_IDENTIFIERS);

return {
  actions: filteredActions.map((action) => ({
    ...(includeIdentifiers && action.id ? { id: action.id } : {}),
    name: action.name,
    // …other properties
  })),
};

When AUTH0_EXPORT_IDENTIFIERS is enabled, the spread operator injects the id property into the exported action object. If disabled, the field is omitted entirely, producing a cleaner configuration that relies on the action name for identification during subsequent imports.

The same pattern appears in src/context/yaml/handlers/actionModules.ts:

const includeIdentifiers = Boolean(context.config.AUTH0_EXPORT_IDENTIFIERS);

return {
  modules: actionModules.map((module) => ({
    ...(includeIdentifiers && module.id ? { id: module.id } : {}),
    module_name: module.module_name,
    // …other properties
  })),
};

Directory Export Behavior

When exporting to directory format, the CLI applies identical logic to strip or preserve identifiers. In src/context/directory/index.ts, the code explicitly handles client identifiers based on the flag status:

// Must copy as the client_id will be stripped if AUTH0_EXPORT_IDENTIFIERS is false
if (!this.config.AUTH0_EXPORT_IDENTIFIERS) {
  // omit client_id …
}

This ensures consistent behavior across both YAML and directory export formats, with the client_id field being removed from exported client configurations when the flag is disabled.

Practical Usage Examples

You can enable identifier export via environment variable when running the CLI:

# Export with identifiers for deterministic round-trip

AUTH0_EXPORT_IDENTIFIERS=true node lib/index.js export -c config.json -f yaml -o ./exported

# Export without identifiers for portable, tenant-agnostic files

AUTH0_EXPORT_IDENTIFIERS=false node lib/index.js export -c config.json -f yaml -o ./exported

Alternatively, configure the flag permanently in your JSON or YAML configuration file:

{
  "AUTH0_EXPORT_IDENTIFIERS": true,
  "AUTH0_DOMAIN": "mytenant.auth0.com",
  "AUTH0_CLIENT_ID": "...",
  "AUTH0_CLIENT_SECRET": "..."
}

Summary

• AUTH0_EXPORT_IDENTIFIERS is a boolean global flag defined in src/types.ts that defaults to false.
• When enabled, Auth0-generated identifiers like id and client_id are preserved in exported files, enabling exact re-imports to the same tenant.
• When disabled, identifiers are stripped by handlers in src/context/yaml/handlers/actions.ts, src/context/yaml/handlers/actionModules.ts, and src/context/directory/index.ts, producing portable configurations.
• Set the flag via environment variable or configuration file depending on whether you need round-trip fidelity or environment portability.

Frequently Asked Questions

What happens if I don't set AUTH0_EXPORT_IDENTIFIERS?

If you omit the flag, it defaults to false, and the export process strips all Auth0-generated identifiers from the output files. This produces clean, tenant-agnostic configurations that rely on resource names for matching during imports, which is ideal for promoting configurations across development, staging, and production tenants.

Can I use AUTH0_EXPORT_IDENTIFIERS with both YAML and directory formats?

Yes, the flag works identically across both export formats. Whether you export to YAML using -f yaml or to directory structure using -f directory, handlers in both src/context/yaml/ and src/context/directory/ check the configuration value to determine whether to include identifiers like id and client_id in the generated files.

Does AUTH0_EXPORT_IDENTIFIERS affect import operations?

The flag only controls export behavior; however, it indirectly affects imports. When identifiers are included in the exported files (true), the CLI can match resources by their exact IDs during import, preventing duplicate creation. When identifiers are excluded (false), the CLI matches resources by name or other mutable attributes, which may result in new resources being created if names differ between tenants.

When should I enable AUTH0_EXPORT_IDENTIFIERS?

Enable this flag when you need to create a complete backup of a specific tenant that you intend to restore to the same tenant instance, such as for disaster recovery or version control of an exact tenant state. Disable it when managing infrastructure-as-code across multiple tenants or environments, where hardcoded IDs would cause conflicts and you want the flexibility to deploy the same configuration file to different Auth0 domains.

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