wholetrans/docs-mastodon
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document new OAuth changes for 4.3.0 (#1445)

Browse source 
* Improve deprecation messaging for Application#vapid_key

* Format JSON examples in Instance methods

* Remove vapid_key from Apps API examples, since this property is deprecated on Application entity

* Add documentation for new OAuth 2.0 features added in 4.3.0

* Improve documentation for oauth-scopes

* Update content/en/api/oauth-scopes.md

Co-authored-by: Matt Jankowski <matt@jankowski.online>

* Update content/en/api/oauth-scopes.md

Co-authored-by: Matt Jankowski <matt@jankowski.online>

* Update content/en/api/oauth-scopes.md

Co-authored-by: Matt Jankowski <matt@jankowski.online>

* Update content/en/api/oauth-scopes.md

Co-authored-by: Matt Jankowski <matt@jankowski.online>

* Add deprecated and removed shortcode labels

* Use deprecated and removed shortcodes

* Improve OAuth documentation

* More OAuth documentation improvements

* Correct streaming API documentation after 4.2.0 changes

* Add note about improved Push Subscription API validation in 4.3.0

* Fix inconsistent OAuth label formatting

* Add note that there is a relationship between Accounts and the Application used to create them

* Add note that application registration endpoint also supports JSON bodies

* Be consistent in the formatting of placeholder values for Bearer tokens

* code review changes

* Slight changes in wording

* Add documentation for PKCE

* Removal of crypto oauth scope

* Cross-link authorization's scope with the OAuth Scopes documentation

* Update content/en/methods/oauth.md

* Update content/en/api/oauth-scopes.md

---------

Co-authored-by: Matt Jankowski <matt@jankowski.online>
Co-authored-by: David Roetzel <david@roetzel.de>
This commit is contained in:
Emelia Smith 2024-10-10 14:44:19 +02:00 • committed by GitHub
parent c99799ac3e
commit cb3aa4de10
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
63 changed files with 926 additions and 507 deletions
Download patch file Download diff file Expand all files Collapse all files

4
content/en/api/guidelines.md
View file

@ -13,7 +13,7 @@ menu:
{{< page-ref page="client/authorized" >}}
{{< page-relref ref="methods/oauth" caption="oauth methods" >}}
{{< page-relref ref="methods/oauth" caption="OAuth methods" >}}
{{< page-relref ref="api/oauth-scopes" caption="OAuth scopes" >}}
@ -58,7 +58,7 @@ To get around this, Mastodon may return links to a "prev" and "next" page. These
```http
GET https://mastodon.example/api/v1/endpoint HTTP/1.1
Authorization: Bearer token
Authorization: Bearer <access_token>
Link: <https://mastodon.example/api/v1/endpoint?max_id=7163058>; rel="next", <https://mastodon.example/api/v1/endpoint?min_id=7275607>; rel="prev"
[

231
content/en/api/oauth-scopes.md
View file

@ -9,130 +9,161 @@ menu:
## 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).
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]({{< relref "api/oauth-tokens" >}}). 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`.
{{< 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`.
To just retrieve the details of the currently authenticated user, use the `profile` scope, which can only access the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/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.
{{</ hint >}}
### Discovering OAuth Scopes supported by a given Mastodon Server
As of Mastodon 4.3.0, support for [RFC 8414](https://tools.ietf.org/html/rfc8414)'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.
{{< hint style="info" >}}
**Example:** You want to use the `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.
{{< /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.
{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}}
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.
### 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.
{{< 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` name instead.
{{< /hint >}}
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.
{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}}
### 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.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)
- 0.9.0 - Added read, write, follow scopes
- 2.4.0 - Added push scope for push notifications
- 2.4.3 - Added granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929)
- 2.6.0 - Deprecated `read:reports` (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
- 2.6.0 - Added `write:conversations` [#9009](https://github.com/mastodon/mastodon/pull/9009)
- 2.9.1 - Added administrative and moderation scopes [#9387](https://github.com/mastodon/mastodon/pull/9387)
- 3.1.0 - Added bookmark scopes [#7107](https://github.com/mastodon/mastodon/pull/7107)
- 3.5.0 - Deprecated `follow` scope in favour of granular scopes [#17678](https://github.com/mastodon/mastodon/pull/17678)
- 4.1.0 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
- 4.3.0 - Added `profile` scope to obtain only information about the currently authenticated user [#29087](https://github.com/mastodon/mastodon/pull/29087), [#30357](https://github.com/mastodon/mastodon/pull/30357)
## List of scopes
## List of high-level scopes
We recommend that you use the [granular scopes](#granular-scopes) shown in the right column of the table below, instead of using the following scopes:
- `read`
- `write`
- `follow` {{%deprecated%}}
- `admin:read`
- `admin:write`
When only the information about the currently authenticated user is required, use the `profile` scope.
### `profile` {#profile}
Grants access only to the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) endpoint. Allowing you to retrieve information about only the currently authenticated user.
### `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-scopes) 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`
### `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.
{{< /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 write data. Requesting `write` will also grant [granular scopes](#granular-scopes) 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}
### `follow` {#follow}
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular `admin` scope):
{{< hint style="danger" >}}
**Deprecated**\
This scope has been deprecated in 3.5.0 and newer. You should instead request the [granular scopes](#granular-scopes) individually, or request `read`/`write` scopes as needed.
{{< /hint >}}
* `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`
Grants access to manage relationships. Requesting `follow` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
### `admin:read` and `admin:write` {#admin}
Used for administrative and moderation APIs. Added in Mastodon 2.9.1.
Requesting `admin:read` or `admin:write` will also grant [granular scopes](#granular-scopes) 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 |
| :------------------------ | :----------------------------------- |
| `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 {#removed}
* Mastodon versions from 3.2.0 to 4.3.0 did support a `crypto` scope 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.

27
content/en/api/oauth-tokens.md Normal file
View file

@ -0,0 +1,27 @@
---
title: OAuth Tokens
description: Defining what token types are used throughout this documentation
menu:
docs:
weight: 15
parent: api
---
## OAuth Tokens
Mastodon supports two different types of OAuth Tokens: App tokens and User tokens. Throughout this documentation you will see these token types referenced in the `OAuth` field for API endpoints.
The `OAuth` field also references Public, in which case no OAuth access token needs to be supplied to access the API endpoint.
### App tokens
In order to receive an App token, you must perform a [client credentials grant flow]({{<relref "client/token#flow" >}}), which gives you a token that can be used to interact with the API on behalf of the OAuth Application. Currently the only API endpoints that accepts this token type are:
- [`GET /api/v1/apps/verify_credentials`]({{<relref "methods/apps#verify_credentials" >}})
- [`POST /api/v1/accounts`]({{<relref "/methods/accounts#create" >}})
### User tokens
In order to create a User token, you must perform a [authorization code grant flow]({{<relref "client/authorized#flow">}}), which gives you an access token that is associated with the user who approves the access grant request.
Many Mastodon APIs require User tokens and specific scopes to access them.