documentation/content/en/api/oauth-scopes.md

4.8 KiB
Raw Blame History

title description menu
OAuth Scopes Defining what you have permission to do with the API
docs
weight parent
20 api

OAuth Scopes

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).

{{< hint style="info" >}} Mind the scope vs scopes difference. This is because scope is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodons own REST API uses the more appropriate scopes. {{< /hint >}}

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 read access.

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.

Version history

  • 0.9.0 - read, write, follow
  • 2.4.0 - push
  • 2.4.3 - granular scopes #7929
  • 2.6.0 - read:reports deprecated (unused stub) #8736/adcf23f
  • 2.6.0 - write:conversations added #9009
  • 2.9.1 - Admin scopes added #9387
  • 3.1.0 - Bookmark scopes added #7107
  • 4.1.0 - Added admin scopes for blocks and allows #20918

List of scopes

read

Grants access to read data. Requesting read will also grant child scopes shown in the left column of the table below.

  • read
    • read:accounts
    • read:blocks
    • read:bookmarks
    • read:favourites
    • read:filters
    • read:follows
    • read:lists
    • read:mutes
    • read:notifications
    • read:search
    • read:statuses

write

Grants access to write data. Requesting write will also grant child scopes shown in the right column of the table below.

  • 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

{{< hint style="danger" >}} Deprecated
This scope has been deprecated in 3.5.0 and newer. You should instead request the child scopes individually, or request read/write permission as needed. {{< /hint >}}

Grants access to manage relationships. Requesting follow will also grant the following child scopes, shown in bold in the table:

  • read:blocks, write:blocks
  • read:follows, write:follows
  • read:mutes, write:mutes

push

Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.

Admin scopes

Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular admin scope):

  • 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

Granular scopes

read write
read:accounts write:accounts
read:blocks write:blocks
read:bookmarks write:bookmarks
write:conversations
read:favourites write:favourites
read:filters write:filters
read:follows write:follows
read:lists write:lists
write:media
read:mutes write:mutes
read:notifications write:notifications
write:reports
read:search
read:statuses write:statuses
admin:read admin:write
admin:read:accounts admin:write:accounts
admin:read:reports admin:write:reports
admin:read:domain_allows admin:write:domain_allows
admin:read:domain_blocks admin:write:domain_blocks
admin:read:ip_blocks admin:write:ip_blocks
admin:read:email_domain_blocks admin:write:email_domain_blocks
admin:read:canonical_email_blocks admin:write:canonical_email_blocks