When you see the error Invalid Token in a third-party Mastodon client, your app cannot authenticate with your Mastodon account. This usually happens because the access token the client uses has expired, been revoked, or was never generated correctly. The token is a secret key that proves your identity to the Mastodon API. This article explains why the error occurs and provides clear steps to fix it on any third-party client.
You may encounter this error on apps like Tusky, Fedilab, or Mastonaut. The fix involves generating a new token or re-authorizing the app. In some cases, the problem is on the server side, such as a changed password or a disabled OAuth app. Follow the steps below to restore access quickly.
Key Takeaways: Fixing Invalid Token in Third-Party Mastodon Clients
- Settings > Authorized apps > Revoke: Remove the problematic client token from your Mastodon account.
- Client settings > Log out and log in again: Forces the app to request a new access token.
- Preferences > Account > Change password: Automatically revokes all existing tokens if you suspect a security issue.
Why Third-Party Clients Show Invalid Token
Mastodon uses OAuth 2.0 for third-party client authentication. When you log into an app, Mastodon issues an access token that the client stores locally. This token expires after a set period, usually several months, or can be revoked immediately if you change your password, disable the app from your account settings, or the app developer updates the client ID. The token is a string of characters that the app sends with every API request. If the token is missing, expired, or does not match what Mastodon expects, the server returns an Invalid Token error.
Some clients cache the token incorrectly after an update. Others may have a bug that corrupts the token during storage. Server-side changes, such as an administrator disabling OAuth for your instance, can also trigger this error. Understanding the cause helps you choose the right fix: re-authorization, token regeneration, or server-side checks.
Steps to Generate a New Access Token and Fix the Error
- Log out of the third-party client
Open the app and find the logout option. In Tusky, go to the sidebar and tap your username, then select Log out. In Fedilab, go to Settings > Account > Log out. This clears the stored token from the app. - Log back in using your Mastodon credentials
Enter your full Mastodon handle (username@instance) and password. The app will request a new token from your instance. Make sure you type the instance URL correctly. For example, use mastodon.social not www.mastodon.social. - Check your Authorized apps on the Mastodon web interface
Open your Mastodon instance in a browser. Go to Preferences > Account > Authorized apps. Look for the third-party client name. If you see it, tap Revoke to remove the old token. Then log in again from the app to create a fresh token. - If the error persists, change your Mastodon password
On the web interface, go to Preferences > Account > Change password. Enter a new strong password. This action revokes all existing tokens for every connected app. After saving, log into the third-party client again with your new password. - Update the third-party client to the latest version
Go to your device app store and check for updates. Developers sometimes fix token-handling bugs. After updating, repeat steps 1 through 3. - Clear the app cache (Android and iOS)
On Android, go to Settings > Apps > [client name] > Storage > Clear cache. On iOS, offload the app: Settings > General > iPhone Storage > [client name] > Offload App. Then reinstall from the App Store. This removes any corrupted token files.
If Mastodon Still Shows Invalid Token After the Main Fix
Token Expired Due to Server Policy
Some Mastodon instances set a short token lifetime. Check your instance documentation or contact the admin. If tokens expire every 24 hours, you must log in daily. Switch to an instance with a longer token lifetime or use the official Mastodon app which handles token refresh automatically.
Client ID and Secret Mismatch
If you manually entered a client ID and secret in a custom client, verify they match the values from the Mastodon instance. Go to Preferences > Development > Your applications. Create a new application if needed. Copy the exact client ID and secret into the client settings. A single wrong character causes the Invalid Token error.
Two-Factor Authentication Interference
If you have two-factor authentication enabled, some third-party clients require an app password instead of your main password. Generate an app password in Preferences > Account > Two-factor Auth. Use that password when logging into the third-party client. The regular password with 2FA code may fail and produce an Invalid Token error.
| Item | Log out and log in again | Revoke token in Authorized apps |
|---|---|---|
| Action | Clears local token and requests a new one | Removes the token from the server side |
| When to use | First troubleshooting step for any token error | If logout alone does not fix the error |
| Effect on other clients | None | All tokens for that app are revoked |
| Requires password | Yes | No, done from web interface |
| Time to complete | 1 minute | 30 seconds |
If you still see the Invalid Token error after trying all steps, test with a different third-party client. This helps you isolate whether the problem is with the app or your Mastodon account. You can now resolve the error by revoking old tokens and re-authorizing the app. For ongoing use, check your authorized apps list monthly and remove any clients you no longer use. As an advanced tip, enable two-factor authentication and generate an app password for each third-party client to improve security without breaking token authentication.