Defining what you have permission to do with the API
The API is divided up into access scopes. The scopes are hierarchical, i.e. if you have access to
read, you automatically have access to
read:accounts. It is recommended that you request as little as possible for your application.
Multiple scopes can be requested at the same time: During app creation with the
scopes param, and during the authorization phase with the
scope query param (space-separate the scopes).
scopesdifference. This is because
scopeis a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate
If you do not specify a
scope in your authorization request, or a
scopes in your app creation request, the resulting access token / app will default to
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
- 0.9.0 - read, write, follow
- 2.4.0 - push
- 2.4.3 - granular scopes https://github.com/tootsuite/mastodon/pull/7929
- 2.6.0 - read:reports deprecated (unused stub) https://github.com/tootsuite/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f
- 2.6.0 - write:conversations added https://github.com/tootsuite/mastodon/pull/9009
- 2.9.1 - Admin scopes added https://github.com/tootsuite/mastodon/pull/9387
- 3.1.0 - Bookmark scopes added
List of scopes
Grants access to read data. Requesting
read will also grant child scopes shown in the left column of the table below.
Grants access to write data. Requesting
write will also grant child scopes shown in the right column of the table below.
Grants access to manage relationships. Requesting
follow will also grant the following child scopes, shown in bold in the table:
Grants access to Web Push API subscriptions. Added in Mastodon 2.4.0.
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular
Last updated January 12, 2020 · Improve this page