For frequent, large-scale user resets in test environments, deleting and recreating the tenant is the recommended approach over bulk user deletion. While there's no "near-instant" bulk deletion method, tenant recreation is significantly faster than iterative bulk deletes at scale.
Key Points About Bulk Delete
Delete Users by Query
is driven by the search index (specifically Elasticsearch). The queryString parameter has limited support when using the database as the search engine (only simple single-term searches on basic fields like firstName, lastName, fullName, email, and username).
CloudFront has a
30-second timeout for origin responses, which explains the 504 errors you're seeing
The delete operation likely continues on the FusionAuth side even after CloudFront terminates the connection, making retries risky
Recommended Approach: Tenant Delete/Recreate
For test environments with large user populations, follow this workflow:
Cannot delete the Default tenant — the default tenant contains the FusionAuth application and cannot be deleted. Create separate tenants for testing purposes.
Delete the test tenant when ready to reset using the admin UI or the
Delete Tenant API. This will permanently delete all users, applications, and groups belonging to that tenant.
Use docker compose down -v to fully clean the environment
Use docker compose up -d to restart
Use Kickstart to automatically recreate tenants, applications, and API keys
Kickstart will only run on an empty instance, so the down -v step is necessary. Configure a Kickstart file with your test environment configuration (tenants, applications, API keys) for reproducible deployments.
Note that tenant deletion is an asynchronous operation (as of FusionAuth 1.22), meaning it runs in the background. For very large tenants (2M users), this will still take time but is considerably faster than bulk deleting millions of users through the API.
Note on Import Timeouts
If you're also seeing CloudFront timeouts during large batch imports (e.g., 100k users), the same 30-second CloudFront limit applies. Consider reducing batch sizes when users have multiple registrations, as each registration inserts additional rows into related tables (registrations, application role mappings, etc.), significantly increasing processing time. For best import performance, minimize network hops and consider setting validateDbConstraints to false.
Related Documentation
Delete Tenant API - API for permanently deleting a tenant and all its users
Bulk Delete Users API - API for deleting users by query, with limitations noted for search engine configuration
Kickstart - Declarative tool for quickly replicating environments
Clean Up Test Environments - Migration guide with recommendations for test tenant cleanup
How to Delete Users After Testing a Migration - Documentation on fastest methods for removing test users
Asynchronous Tenant Deletion - Background on how tenant deletion works asynchronously
Import Users API - Bulk import API documentation
Performance Tips for Migrations - Best practices for importing large numbers of users
