OAuth Scopes
Defining what you have permission to do with the API
OAuth Scopes
The API access is divided up into several OAuth scopes, these limit what an API client can do, based on the registered and requested scopes for the Access Token. The scopes in Mastodon are hierarchical, for example, if you request the read scope, you automatically have access to read:accounts, however we recommend that you request the most limited scopes as possible for your application, i.e., if you only need read access to lists and the current user profile, then you should use profile read:lists as your scopes instead of read.
profile scope, which can only access the GET /api/v1/accounts/verify_credentials endpoint.This scope was added in Mastodon 4.3, so we recommend using the “Discovering OAuth Scopes supported by a given Mastodon Server” guidance below when using this scope.
Discovering OAuth Scopes supported by a given Mastodon Server
As of Mastodon 4.3.0, support for RFC 8414’s GET /.well-known/oauth-authorization-server endpoint was added, allowing you to discover the scopes supported by the Mastodon server (as well as other OAuth related information such as the endpoints and grant flows).
We recommended using this endpoint in order to support multiple versions of Mastodon for your OAuth Application.
If you make a request to the GET /.well-known/oauth-authorization-server endpoint, and it returns a 404, then you can assume that the Mastodon server is running a version older than 4.3, in which case you’ll need to look at the specific scopes your application needs and what the lowest common scopes are for the version range of Mastodon that you wish to support.
profile scope, but also want to support older Mastodon servers that don’t have that scope and would need read:accounts instead. You could discover whether a server supports that scope by making a request this endpoint.Multiple scopes can be requested at the same time
During application creation you can specify multiple space-separated scopes with the scopes parameter. During the authorization phase you can do the same with the scope query parameter.
scope vs scopes difference. This is because scope is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate scopes name instead.If you do not specify scope in your authorization request, or scopes in your application creation request, the resulting access token/app will be assigned the default scope. This is currently read as of Mastodon 4.3, but is subject to change in the future.
Version history
- 0.9.0 - Added read, write, follow scopes
- 2.4.0 - Added push scope for push notifications
- 2.4.3 - Added granular scopes #7929
- 2.6.0 - Deprecated
read:reports(unused stub) #8736/adcf23f - 2.6.0 - Added
write:conversations#9009 - 2.9.1 - Added administrative and moderation scopes #9387
- 3.1.0 - Added bookmark scopes #7107
- 3.5.0 - Deprecated
followscope in favour of granular scopes #17678 - 4.1.0 - Added admin scopes for blocks and allows #20918
- 4.3.0 - Added
profilescope to obtain only information about the currently authenticated user #29087, #30357
List of high-level scopes
We recommend that you use the granular scopes shown in the right column of the table below, instead of using the following scopes:
readwritefollowdeprecatedadmin:readadmin:write
When only the information about the currently authenticated user is required, use the profile scope.
profile
Grants access only to the GET /api/v1/accounts/verify_credentials endpoint. Allowing you to retrieve information about only the currently authenticated user.
read
Grants access to read data, including other users. Requesting read will also grant granular scopes shown in the right column of the table below.
write
Grants access to write data. Requesting write will also grant granular scopes shown in the right column of the table below.
push
Grants access to Web Push API subscriptions. Added in Mastodon 2.4.0.
follow
This scope has been deprecated in 3.5.0 and newer. You should instead request the granular scopes individually, or request
read/write scopes as needed.Grants access to manage relationships. Requesting follow will also grant granular scopes shown in the right column of the table below.
admin:read and admin:write
Used for administrative and moderation APIs. Added in Mastodon 2.9.1.
Requesting admin:read or admin:write will also grant granular scopes shown in the right column of the table below.
admin scope available.Granular scopes
It is recommended that you make use of granular scopes, unless you really need full access to everything by using a scope of read write follow push.
| Scope | Granular Scopes |
|---|---|
profile | |
push | |
read | |
read:accounts | |
read:blocks | |
read:bookmarks | |
read:favourites | |
read:filters | |
read:follows | |
read:lists | |
read:mutes | |
read:notifications | |
read:search | |
read:statuses | |
write | |
write:accounts | |
write:blocks | |
write:bookmarks | |
write:conversations | |
write:favourites | |
write:filters | |
write:follows | |
write:lists | |
write:media | |
write:mutes | |
write:notifications | |
write:reports | |
write:statuses | |
follow deprecated | |
read:follows | |
write:follows | |
read:blocks | |
write:blocks | |
read:mutes | |
write:mutes | |
admin:read | |
admin:read:accounts | |
admin:read:reports | |
admin:read:domain_allows | |
admin:read:domain_blocks | |
admin:read:ip_blocks | |
admin:read:email_domain_blocks | |
admin:read:canonical_email_blocks | |
admin:write | |
admin:write:accounts | |
admin:write:reports | |
admin:write:domain_allows | |
admin:write:domain_blocks | |
admin:write:ip_blocks | |
admin:write:email_domain_blocks | |
admin:write:canonical_email_blocks |
Removed scopes
- Mastodon versions from 3.2.0 to 4.3.0 did support a
cryptoscope for end-to-end encryption APIs, however, this functionality was never documented nor fully implemented, and has been removed as of version 4.3.0. Any applications registered with that scope will have the scope removed when the server is upgraded to 4.3.0 and above.
Last updated October 10, 2024 · Improve this page