How to Fix Mastodon Error ‘OAuth App Authorization Failed’

You try to log in to Mastodon using a third-party app like Tusky, Fedilab, or Metatext and see the error message: OAuth App Authorization Failed. This error occurs because the OAuth handshake between the app and the Mastodon server breaks due to a mismatched redirect URI, expired token, or blocked callback. This article explains the three main causes and gives you step-by-step fixes for each one.

Why the OAuth App Authorization Failed Error Appears

Mastodon uses the OAuth 2.0 protocol so third-party apps can access your account without storing your password. When you tap Authorize in the app, Mastodon sends a temporary code to the app. The app then exchanges that code for an access token. If any part of this exchange fails, you see the OAuth App Authorization Failed error.

The three most common root causes are:

Mismatched Redirect URI

Each OAuth app registers a redirect URI with the Mastodon server. When you authorize the app, Mastodon sends the authorization code to that exact URI. If the app uses a different URI at runtime, the server rejects the response. This mismatch happens most often after you update the app or switch between multiple Mastodon instances.

Expired or Revoked Token

Access tokens in Mastodon do not expire by default, but they can be manually revoked from your account settings. If you previously revoked the app token or changed your password, the old token becomes invalid. The app then attempts to use a dead token and fails with the authorization error.

Blocked or Cached Callback URL

Some browsers or DNS providers block custom URL schemes like tusky://callback. When the Mastodon server tries to redirect back to the app, the browser intercepts the URL and shows an error page instead of handing the code to the app. DNS caching can also redirect the callback to an old IP address, causing the same failure.

Steps to Fix the OAuth App Authorization Failed Error

Follow these steps in order. After each step, try authorizing the app again. If the error persists, move to the next step.

Step 1: Revoke the Existing App Token from Mastodon

1. Open Mastodon preferences
   Log in to your Mastodon instance in a web browser. Click the gear icon or your profile picture, then select Preferences from the menu.
2. Navigate to Applications
   In the left sidebar, click Applications. You see a list of every third-party app that has an active token for your account.
3. Find the failing app
   Locate the app that shows the authorization error. The name matches the app you are using, for example Tusky or Fedilab.
4. Click Revoke
   Click the Revoke button next to the app name. This invalidates the current token immediately.
5. Re-authorize the app
   Open the third-party app again and go through the login flow. The app requests a new token from Mastodon and the error should no longer appear.

Step 2: Verify the App Redirect URI

1. Check the app settings
   Open the third-party app and look for a setting labeled Server URL, Instance, or Custom Domain. Some apps let you manually type the instance address.
2. Confirm the redirect URI
   Most Mastodon apps use one of these redirect URIs: urn:ietf:wg:oauth:2.0:oob for desktop web apps, or a custom scheme like tusky://callback for Android apps. If the app lets you edit the redirect URI, set it to the correct value for that app.
3. Reinstall the app if needed
   If the app does not expose the redirect URI in its settings, uninstall the app and install the latest version from the official store. The fresh install registers the correct URI with the Mastodon server.

Step 3: Clear Browser Cache and DNS Cache

1. Clear browser cache
   In your default browser, open Settings > Privacy and security > Clear browsing data. Select Cached images and files and Cookies and other site data. Click Clear data.
2. Flush DNS cache
   On Windows 10 and Windows 11, open Command Prompt as administrator. Type ipconfig /flushdns and press Enter. On macOS, open Terminal and type sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder.
3. Retry the authorization
   Close the browser completely. Open the third-party app and start the authorization flow again.

Step 4: Use a Different Browser for the Authorization Step

1. Change the default browser
   If your default browser blocks custom URL schemes, switch to a different browser temporarily. For example, if you use Chrome, set Firefox as the default browser in your operating system settings.
2. Authorize the app again
   Open the third-party app and start the login process. The app opens the new browser. Complete the authorization there.
3. Switch back to the original browser
   After the authorization succeeds, you can restore your previous default browser.

If the Error Still Appears After the Main Fixes

App Shows OAuth Error After a Mastodon Server Upgrade

Some Mastodon instances upgrade to a newer version that deprecates older OAuth endpoints. If the third-party app has not been updated in more than six months, it may still call the old endpoint. Check the app’s official website or repository for an update. If no update exists, consider switching to a different Mastodon app that supports the current API version.

OAuth Error Only on a Specific Network

Corporate or school networks sometimes block OAuth callback URLs because they contain custom URI schemes. Connect to a different network, for example your home Wi-Fi or a mobile hotspot. If the authorization succeeds on the other network, the issue is with the network firewall, not with Mastodon. Contact your network administrator to allow the specific callback URL.

Multiple Accounts on the Same Instance Cause Confusion

If you manage more than one Mastodon account on the same instance, the browser may cache the wrong account session. Log out of all Mastodon accounts in the browser. Then start the authorization flow from the app and log in with the correct account only.

Mastodon OAuth vs Manual Token Entry: Which Method Works Best

Item	OAuth Authorization	Manual Token Entry
Description	App requests a token through the standard browser-based redirect flow	User generates a token in Mastodon preferences and pastes it into the app
Security	No password shared with the app; token scoped to specific permissions	Same security level; token is still scoped but must be manually copied
Ease of use	One-click authorization in the browser	Requires navigating to Preferences > Development > New Application
Best for	Most users and modern apps	Apps that cannot open a browser or users behind strict firewalls
Common failure	Redirect URI mismatch or blocked callback	Token copied incorrectly or expires

The OAuth authorization method is the recommended approach for most Mastodon apps. Manual token entry works as a fallback when the OAuth flow consistently fails due to network restrictions or outdated app code.