zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity

Improve documentation for oauth-scopes

This commit is contained in:
Emelia Smith 2024-05-15 21:09:16 +02:00
parent 1b3b46d15e
commit 9e25eff983
No known key found for this signature in database
1 changed files with 104 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
content/en/api/oauth-scopes.md
View File

@ -11,128 +11,145 @@ menu:
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" >}}
If you just want to retrieve the basic details of the currently authenticated user, use the `read:me` scope, which can only access the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) endpoint.
{{</ hint >}}
### Discovering OAuth Scopes supported by a given Mastodon Server
As of Mastodon 4.3.0, we can make a request to `GET /.well-known/oauth-authorization-server` to discover the scopes supported by the Mastodon server (as well as other OAuth related information such as endpoints and grant flows).
It is recommended that you do this if you need to support multiple versions of Mastodon for your OAuth Application.
{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}}
### Multiple scopes can be requested at the same time
During application creation with the `scopes` parameter you can specify multiple space-separated scopes, and during the authorization phase with the `scope` query parameter (space-separate the scopes).
{{< hint style="danger" >}}
The set of scopes saved during application creation must include all the scopes that you will request in the authorization request, otherwise, authorization will fail.
{{< /hint >}}
{{< 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`.
{{< /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.
If you do not specify a `scope` in your authorization request, or a `scopes` in your application creation request, the resulting access token/app will default to `read` access. This is subject to change in the future.
### Version history {#versions}
- 0.9.0 - read, write, follow
- 2.4.0 - push
- 2.4.3 - granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929)
- 2.6.0 - read:reports deprecated (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - write:conversations added [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.4.3 - granular scopes added [#7929](https://github.com/mastodon/mastodon/pull/7929)
- 2.6.0 - `read:reports` deprecated (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - `write:conversations` added [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.9.1 - Admin scopes added [#9387](https://github.com/mastodon/mastodon/pull/9387)
- 3.1.0 - Bookmark scopes added [#7107](https://github.com/mastodon/mastodon/pull/7107)
- 4.1.0 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
- 4.3.0 - Added `read:me` scope for when you want just basic information about the currently authenticated account. [#29087](https://github.com/mastodon/mastodon/pull/29087)
## List of scopes
## List of high-level scopes
We recommend that you use the [granular scopes](#granular) shown in the right column of the table below, instead of using the following scopes:
- `read`
- `write`
- `follow` (deprecated)
- `admin:read`
- `admin:write`
If you just want to retrieve the basic details of the currently authenticated user, use the `read:me` scope.
### `read:me` {#read-me}
Grants access only to the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) endpoint. Allowing you to retrieve information only about the currently authenticated account.
### `read` {#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`
Grants access to read data, including other users. Requesting `read` will also grant [granular scopes](#granular) shown in the right column of the table below.
### `write` {#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`
Grants access to write data. Requesting `write` will also grant [granular scopes](#granular) shown in the right column of the table below.
### `follow` {#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.
This scope has been deprecated in 3.5.0 and newer. You should instead request the [granular scopes](#granular) individually, or request `read`/`write` scopes 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`
Grants access to manage relationships. Requesting `follow` will also grant [granular scopes](#granular) shown in the right column of the table below.
### `push` {#push}
Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.
### Admin scopes {#admin}
### `admin:read` and `admin:write` {#admin}
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular `admin` scope):
Used for administrative and moderation APIs. Added in Mastodon 2.9.1.
* `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`
Requesting `admin:read` or `admin:write` will also grant [granular scopes](#granular) shown in the right column of the table below.
{{< hint style="info" >}}
Note that there is no singular `admin` scope available.
{{< /hint >}}
## Granular scopes {#granular}
| 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 |
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`.
| 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 |
| Scope | Granular Scopes |
| :-------------------- | :----------------------------------- |
| `read` | |
| | `read:accounts` |
| | `read:blocks` |
| | `read:bookmarks` |
| | `read:favourites` |
| | `read:filters` |
| | `read:follows` |
| | `read:lists` |
| | `read:mutes` |
| | `read:notifications` |
| | `read:search` |
| | `read:statuses` |
| | `read:me` |
| `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` |
| `push` | |
| `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` |