Skip to main content
Permanently delete an organization and all its associated resources. This action cannot be undone.
This is a destructive operation. Deleting an organization will:
  • Remove the organization and all its data
  • Delete all projects within the organization
  • Remove all user memberships and permissions
  • Delete all service users and credentials
  • Remove all billing information and invoices
  • Clear all audit logs
This operation is irreversible. Consider disabling the organization instead if you may need to restore it later.

​
Path Parameters

​
id
string
required
The organization identifier. Can be either:
  • Organization UUID (e.g., 9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e)
  • Organization name/slug (e.g., acme-corp)

​
Response

Returns an empty response with status code 200 on success. 
curl -X DELETE 'https://api.frontier.example.com/v1beta1/organizations/acme-corp' \
  -H 'Authorization: Bearer <token>'

​
Response Example

{}
A successful deletion returns an empty JSON object with HTTP status 200.

​
Error Responses

​
code
string
Error code indicating the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • 401 Unauthorized: Invalid or missing authentication token
  • 403 Forbidden: User doesn’t have permission to delete the organization
    • Only organization owners/admins can delete organizations
    • Some deployments may restrict deletion to super admins only
  • 404 Not Found: Organization doesn’t exist or has already been deleted
  • 500 Internal Server Error: Server encountered an unexpected error during deletion

​
Deletion Process

When you delete an organization, the following happens in order:
  1. Validation: Checks if the organization exists and user has permission
  2. Cascading Deletion:
    • All projects and their resources are deleted
    • All user memberships and role assignments are removed
    • All service users and their credentials are deleted
    • All policies and permissions are removed
    • Billing information is archived/deleted
  3. Organization Removal: The organization record is permanently deleted
  4. Audit Log: A final audit entry is created before deletion

​
Alternatives to Deletion

If you want to temporarily deactivate an organization instead of permanent deletion, consider:
  • Disable Organization: Use the POST /v1beta1/organizations/{id}/disable endpoint to disable the organization while preserving all data
  • Change State: Disabled organizations can be re-enabled later with POST /v1beta1/organizations/{id}/enable

​
Best Practices

  1. Backup Important Data: Export any data you may need later
  2. Notify Members: Inform all organization members about the deletion
  3. Review Dependencies: Check for any external integrations or API keys
  4. Cancel Billing: Ensure billing is canceled to avoid future charges
  5. Consider Disabling First: Try disabling the organization for a period before permanent deletion
In production applications, implement a confirmation flow:
// Example confirmation flow
const confirmDelete = window.confirm(
  `Are you sure you want to delete ${orgName}? ` +
  'This will permanently delete all data and cannot be undone. ' +
  'Type the organization name to confirm.'
);

if (confirmDelete) {
  const userInput = window.prompt(
    `Type "${orgName}" to confirm deletion:`
  );
  
  if (userInput === orgName) {
    await deleteOrganization(orgId);
  }
}
Deletion may fail if:
  • The organization has active billing subscriptions
  • There are locked resources or pending operations
  • Database constraints prevent deletion
Implement proper error handling and retry logic:
import time

def safe_delete_organization(org_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = delete_organization(org_id)
            return response
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

​
Notes

  • Organization deletion is typically restricted to owners or super admins
  • Some deployments may implement soft deletion where data is marked as deleted but retained for a period
  • The organization name becomes available for reuse after deletion
  • Any API tokens or credentials associated with the organization are immediately invalidated
  • Billing is automatically canceled upon deletion
  • Consider implementing a “grace period” in your application where users can cancel the deletion

Build docs developers (and LLMs) love

Get started for freeTalk to us