> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/api/oauth-scopes.md).

# OAuth Scopes

## 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. Mastodon’s own REST API uses the more appropriate `scopes`.
{% endhint %}

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

### `read`

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

### `write`

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

### `follow`

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.](/mastodon/methods/notifications/push.md) 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:write`
  * `admin:write:accounts`
  * `admin:write:reports`

## 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  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mastodon.gitbook.io/mastodon/api/oauth-scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.