Mastodon Export OAuth App Tokens: Backup and Restore

When you log in to a Mastodon client app like Tusky, Fedilab, or the official Mastodon mobile app, the app receives an OAuth token that grants it permission to act on your behalf. If you lose access to your account or need to switch devices without reauthorizing every app, backing up those tokens saves time and prevents service interruptions. OAuth tokens are stored locally on your device and are not synced across devices by default. This article explains how to export OAuth tokens from Mastodon’s database, back them up safely, and restore them on a new installation or device.

Understanding OAuth Tokens in Mastodon

OAuth 2.0 is the authorization framework that Mastodon uses to let third-party apps access your account without sharing your password. When you authorize an app, Mastodon issues an access token — a string of characters — that the app sends with each API request. The token defines the scope of access, such as reading posts, posting on your behalf, or following accounts.

The token is stored in two places. On the Mastodon server, it lives in the oauth_access_tokens table in the PostgreSQL database. On the client side, the app saves the token in its local storage — often a file in the app’s data directory on desktop or in the system keychain on mobile. Backing up the token means saving it from either location so you can reuse it later without reauthorizing the app.

Why You Might Need to Export Tokens

You might need to export OAuth tokens when moving to a new Mastodon instance, switching client apps, or reinstalling your operating system. Without a backup, each app must be reauthorized individually, which can be tedious if you use several apps. Also, some apps lose their token if you clear the app data, and you would have to log in again.

How to Export OAuth Tokens from Mastodon

There are two primary methods to export OAuth tokens: from the server-side database and from the client-side app data. Choose the method that matches your access level and technical comfort.

Method 1: Export from the Mastodon Server Database

This method requires access to the Mastodon server’s PostgreSQL database. You need the database credentials, which are typically in the .env.production file of your Mastodon installation.

1. Connect to the Mastodon server via SSH
   Log in to your server using SSH. Navigate to the Mastodon directory, usually /home/mastodon/live.
2. Access the Rails console
   Run RAILS_ENV=production bin/rails c to open the Rails console. This gives you direct access to the application models.
3. Query the OAuth access tokens table
   At the console prompt, type Doorkeeper::AccessToken.all.each { |token| puts token.token }. This prints every access token in the database. To filter by user, use Doorkeeper::AccessToken.where(resource_owner_id: USER_ID).each { |token| puts token.token }.
4. Save the output to a file
   Copy the printed tokens and paste them into a secure text file, for example mastodon_tokens_backup.txt. Store this file in an encrypted location.
5. Exit the Rails console
   Type exit and close the SSH session.

Method 2: Export from the Client App Data

For desktop apps like TheDesk or Whalebird, the token is often stored in a JSON configuration file in the user’s app data folder. Mobile apps typically store tokens in the system keychain, which is not easily exportable without jailbreaking or rooting the device.

1. Locate the app’s configuration directory
   On Windows, check %APPDATA%\AppName. On macOS, look in ~/Library/Application Support/AppName. On Linux, check ~/.config/AppName.
2. Find the file containing the token
   Search for files named config.json, settings.json, or tokens.json. Open the file in a text editor and look for a key named access_token or token.
3. Copy the token string
   Select the token value — a long alphanumeric string — and copy it to your clipboard. Paste it into a secure backup file.
4. Also copy the client_id and client_secret if present
   Some apps store the client credentials alongside the token. Save these as well because they are needed to restore the app registration on a new device.

How to Restore OAuth Tokens in Mastodon

Restoring a token depends on whether you are restoring to the same Mastodon instance or a different one. Tokens are tied to a specific instance URL and user account. You cannot reuse a token from instance A on instance B.

Restoring on the Same Instance via Rails Console

1. Open the Rails console
   Run RAILS_ENV=production bin/rails c on the server.
2. Create a new access token record
   Type token = Doorkeeper::AccessToken.new(resource_owner_id: USER_ID, application_id: APP_ID, token: 'YOUR_BACKED_UP_TOKEN', scopes: 'read write follow', expires_in: nil). Replace USER_ID with the user’s ID in the database, APP_ID with the OAuth application’s ID, and the token string with your backup.
3. Save the token
   Type token.save! to persist the token to the database.
4. Verify the token works
   Use a tool like curl to test the token: curl -H "Authorization: Bearer YOUR_BACKED_UP_TOKEN" https://yourinstance.com/api/v1/accounts/verify_credentials. You should receive a JSON response with your account details.

Restoring on a Client App

1. Locate the app’s configuration directory on the new device
   Install the app and run it once to create the configuration folder. Then close the app.
2. Replace the token in the config file
   Open the config file from the backup and paste the token into the corresponding field. If the file also contains client_id and client_secret, replace those as well.
3. Restart the app
   Launch the app. It should now authenticate using the restored token without prompting for login.

Common Issues When Backing Up and Restoring OAuth Tokens

Token Expired or Revoked

Mastodon tokens can expire if the server administrator configured an expiration time. Also, tokens are revoked when the user changes their password or deauthorizes the app from Preferences > Account > Authorized apps. If the token no longer works, you must reauthorize the app normally.

App ID Mismatch

When restoring a token to a different app registration, the application_id must match the original app’s ID. If you registered a new app on the server, the old token will not work with the new app. Always save the client_id and client_secret along with the token.

Scope Changes

If you restore a token with a scope that no longer matches the app’s requested scopes, the API may reject requests. For example, if the original token had read scope but the app now requires write, you need to create a new token with the correct scopes.

Item	Server-side Backup	Client-side Backup
Access required	SSH and database credentials	File system access on the device
Token location	oauth_access_tokens table in PostgreSQL	Local config file or keychain
Best for	Server administrators managing many users	Individual users backing up their own apps
Risk of token theft	High if backup file is not encrypted	Moderate — depends on device security
Portability between instances	Not portable	Not portable

OAuth tokens are tied to a specific Mastodon instance and user account. They cannot be transferred between instances. Always store backup files in an encrypted container or password manager. For most users, the easiest method is to save the token from the client app’s config file. Server administrators should use the Rails console method for bulk operations. After restoring a token, test it with a simple API call to confirm it works before relying on it.