Application access tokens allow third-party services and scripts to interact with your Mastodon account without exposing your login credentials. These tokens authenticate API requests for tasks such as posting content, reading timelines, or managing notifications from external tools. Without a token, any external app would need your email and password, which creates a security risk. This article explains what access tokens are, how to generate them in Mastodon’s settings, and how to use them safely in your own automation projects.
Key Takeaways: Generating and Using Mastodon Application Access Tokens
- Preferences > Development > New Application: Opens the form to register a new app and generate a token.
- Scopes selection during app creation: Controls which API actions the token can perform, such as read, write, or follow.
- Access Token field in app details: Displays the generated token string after you save the application.
What Are Application Access Tokens and Why Do You Need Them
An application access token is a unique string that identifies your Mastodon account to the Mastodon API. When a third-party tool like a cross-poster, a bot framework, or a custom script makes an API call, it sends this token instead of your username and password. The Mastodon server checks the token, sees which permissions it has, and then allows or denies the request.
Mastodon uses the OAuth 2.0 protocol to manage these tokens. OAuth 2.0 is an industry standard for delegated access. It means you do not have to share your Mastodon password with any external service. Instead, you create a token with a limited set of permissions, called scopes. Scopes define exactly what the token can do. For example, a token with only the read scope can view your home timeline but cannot post. A token with write:statuses can publish new toots but cannot delete them.
You need an application access token whenever you want to use a non-official Mastodon client, a command-line tool, or a custom automation script. The Mastodon API uses tokens for every authenticated request. If you try to use the API without a token, the server returns a 401 Unauthorized error. Generating a token from your Mastodon account settings is the standard way to grant API access securely.
Steps to Create an Application Access Token in Mastodon
Follow these steps from the Mastodon web interface. You must be logged in as the account that will own the token. The token you generate will act on behalf of that account only.
- Open the Preferences menu
Click your profile avatar in the top-right corner of the Mastodon interface. A dropdown menu appears. Select Preferences from that menu. - Navigate to the Development section
In the left sidebar of the Preferences page, find the Development link and click it. This opens a page that lists any existing applications you have registered. If you have no applications yet, the list is empty. - Click the New Application button
On the Development page, click the New Application button. This opens a form where you define the app’s name and permissions. - Enter the application name
Type a descriptive name in the Application name field. Use a name that helps you remember what this token is for, such as “Cross-poster to Twitter” or “Personal bot script.” - Set the Redirect URI
For most personal automation tasks, enterurn:ietf:wg:oauth:2.0:oobin the Redirect URI field. This tells the OAuth flow to return the token directly in the browser or script output instead of redirecting to a web page. If you are building a web app that handles the redirect, enter your app’s callback URL instead. - Select the required scopes
Scroll down to the Scopes section. Mastodon groups scopes into categories: read, write, follow, push, and admin. Under each category, you can select sub-scopes such as read:statuses or write:media. Select only the scopes your application actually needs. For example, a bot that only posts status updates needs write:statuses but does not need read or admin. To select a scope, check the box next to it. - Submit the application form
Click the Submit button at the bottom of the form. Mastodon saves the application and redirects you to the application’s detail page. - Copy the access token
On the application detail page, locate the field labeled Your access token. It contains a long alphanumeric string. Click the copy icon next to it or select the text and copy it manually. Store this token in a secure place, such as a password manager or an environment variable file. You cannot see the full token again after you leave this page.
Once you have copied the token, you can use it in any Mastodon API client. For example, in a Python script using the Mastodon.py library, you pass the token as the access_token parameter when creating the Mastodon object. In a curl command, you include it in the HTTP Authorization header as Authorization: Bearer YOUR_TOKEN_HERE.
Common Mistakes and Security Considerations
Token visible in the application list but not copied
Mastodon displays the access token only once, right after you create the application. If you leave the detail page without copying the token, you cannot retrieve it again. You must delete the application and create a new one to get a fresh token. Always copy the token immediately after submission and store it in a safe location.
Selecting too many scopes
Giving a token more scopes than necessary increases risk if the token is leaked. A token with admin scope can perform administrative actions on your account, such as changing settings or viewing direct messages. Restrict scopes to the minimum needed. For a simple read-only script, select only read or read:statuses. For a posting bot, select only write:statuses and write:media if you upload images.
Using the token in client-side JavaScript
Do not embed your access token in JavaScript code that runs in a user’s browser. Anyone who views the page source can see the token. Instead, keep the token on a server you control and make API calls from the server side. If you need to build a client-side Mastodon app, use the full OAuth 2.0 authorization code flow, which redirects the user to Mastodon to grant permission without exposing your token.
Token used in a public GitHub repository
If you accidentally commit a token to a public repository, revoke it immediately. Go to Preferences > Development, click on the application name, and then click the Delete button. Create a new application with a fresh token. To prevent this, use environment variables or a configuration file that is excluded from version control via .gitignore.
Mastodon Access Tokens vs OAuth 2.0 Authorization Code Flow
| Item | Application Access Token | OAuth 2.0 Authorization Code Flow |
|---|---|---|
| Best for | Personal scripts, single-user bots, testing | Multi-user web apps, mobile apps, third-party clients |
| Setup complexity | Low: generate from Preferences page | High: requires a web server to handle redirects and exchange codes |
| Token exposure | Token is static and visible in the UI | Token is exchanged server-side and never exposed to the user |
| Scope granularity | Same as OAuth scopes, selected at creation | Same scopes, but can be requested per session |
| Revocation method | Delete the application in Preferences | Revoke the specific token via API or account settings |
Application access tokens are a simplified version of OAuth 2.0. They skip the redirect step and give you a permanent token directly. Use them for your own automation. For applications that other people will log into, implement the full OAuth flow so each user authenticates with their own Mastodon account.
Now you can generate an application access token from Preferences > Development and use it in any Mastodon API client. For your next automation project, try using the token with a curl command to fetch your home timeline. A practical tip: store the token in an environment variable named MASTODON_ACCESS_TOKEN and reference it in your scripts instead of hardcoding the string. This keeps the token out of your source code and makes it easy to rotate tokens when needed.