Permanent Channel Deletion via API Returns 403 for Archived Channels

Applies to: Mattermost Server (self-managed) with Allow users to view archived channels disabled.

Symptoms: A system admin's API call to permanently delete an archived channel returns HTTP 403 api.context.permissions.app_error, even though EnableAPIChannelDeletion is true.

🛑 Problem

When Allow users to view archived channels is disabled, Mattermost denies all channel-scoped permission checks against archived channels. This restriction applies to every role, including System Admin, and it is evaluated before the permanent-deletion logic runs.

The DELETE /api/v4/channels/{channel_id}?permanent=true endpoint first checks the caller's delete_public_channel or delete_private_channel permission against the target channel. On an archived channel with viewing disabled, that check returns denied before the system-admin fallback is reached, so the request fails with 403. The EnableAPIChannelDeletion setting is never evaluated on this path, so confirming it is enabled does not resolve the error.

Key points that distinguish this issue:

• The restriction applies only to archived channels. A system admin can permanently delete an active (non-archived) channel, but not an archived one, under the same settings.
• The deciding factor is whether the channel is archived, not who created it. A newly created channel is active and deletes normally; the archived channels you are trying to purge are blocked.
• Deployments where Allow users to view archived channels is enabled are not affected.

Symptoms

Users or administrators experiencing this issue will see:

{'id': 'api.context.permissions.app_error', 'message': 'You do not have the appropriate permissions.', 'detailed_error': '', 'status_code': 403}

Additional symptoms:

• The API user is a System Admin (roles: system_user system_admin) and EnableAPIChannelDeletion is true.
• The same user can permanently delete channels it just created (active channels), but not older archived channels.
• No error-level entry appears in the server logs, because permission denials log at debug level only.

✅ Solution

Re-enable archived-channel access, or delete the channels through a path not subject to the restriction. Any one of the three options below resolves the 403.

Option 1: Enable "Allow users to view archived channels"

Navigate to System Console > Site Configuration > Users and Teams > Allow users to view archived channels and set it to true.

Equivalent config.json key and environment variable:

TeamSettings.ExperimentalViewArchivedChannels = true
MM_TEAMSETTINGS_EXPERIMENTALVIEWARCHIVEDCHANNELS=true

Reload the configuration, then re-run your deletion script.

⚠️ Important: This setting controls whether all users can browse and search archived channels, not just your API user. Confirm this visibility is acceptable in your environment before enabling it.

Option 2: Unarchive, then permanently delete

Unarchive each target channel first, then call the permanent-delete API. Active channels are not subject to the restriction.

Option 3: Delete in local mode with mmctl

Run the deletion on the server host in local mode. Local mode runs with unrestricted permissions and bypasses the archived-channel check without changing any setting:

mmctl channel delete --permanent <team>:<channel> --local

⚠️ Important: Permanent deletion is irreversible and removes the channel and all its posts from the database. Local mode requires shell access to the server and the local socket (ServiceSettings.EnableLocalMode) to be enabled.

Additional Resources

For more information, see:

Allow users to view archived channels

Enable API Channel Deletion

mmctl channel delete

Delete a channel (REST API reference)