Document new OAuth changes for 4.3.0

archetypes/methods.md

@@ -32,7 +32,7 @@ x.x.x - added
 ##### Headers
 
 Authorization
-: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
+: {{<required>}} Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
 
 ##### Query parameters
 

assets/style.scss

@@ -32,6 +32,7 @@ $darker: $classic-primary-color;
 
 $vibrant: lighten($blurple-500, 8%); // color4
 $error: $warning-red; // color6
+$warning: $gold-star;
 $success: $success-green; // color7
 
 $background-border-color: lighten($classic-base-color, 4%);
@@ -905,6 +906,20 @@ main {
     color: $error;
   }
 
+  &-removed {
+    text-transform: uppercase;
+    font-size: 12px;
+    font-weight: 500;
+    color: $error;
+  }
+
+  &-deprecated {
+    text-transform: uppercase;
+    font-size: 12px;
+    font-weight: 500;
+    color: $warning;
+  }
+
   &-optional {
     text-transform: uppercase;
     font-size: 12px;

content/en/admin/config.md

@@ -303,10 +303,11 @@ The streaming API can be deployed to a different domain/subdomain. This may impr
 
 Example value: `wss://streaming.example.com`
 
-#### `STREAMING_CLUSTER_NUM` (deprecated) {#streaming_cluster_num}
+#### `STREAMING_CLUSTER_NUM` {{%removed%}} {#streaming_cluster_num}
 
 {{< hint style="danger" >}}
-Deprecated: The streaming server process now only uses a single node.js process, to scale it further, you'll need to follow the documentation in the [scaling guide](/admin/scaling#streaming)
+**Removed:**\
+The streaming server process now only uses a single node.js process, to scale it further, you'll need to follow the documentation in the [scaling guide](/admin/scaling#streaming)
 {{< /hint >}}
 
 Specific to the streaming API, this variable determines how many different processes the streaming API forks into. Defaults to the number of CPU cores minus one.
@@ -1048,7 +1049,7 @@ If set, registrations confirm page will display a captcha, see [Captcha](https:/
 
 If set, registrations will not be possible with any e-mails **except** those from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
 
-#### `EMAIL_DOMAIN_DENYLIST`
+#### `EMAIL_DOMAIN_DENYLIST` {{%deprecated%}}
 
 If set, registrations will not be possible with any e-mails from the specified domains. Pipe-separated values, e.g.: `foo.com|bar.com`
 

content/en/api/guidelines.md

@@ -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"
 [

content/en/api/oauth-scopes.md

@@ -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.**
+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`.
 
-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" >}}
+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 >}}
+
+{{< 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 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`.
+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 a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token/app will default to `read` access.
+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.
 
-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.
+{{< 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`
+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.
 
 ### `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-scopes) 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:
+Grants access to manage relationships. Requesting `follow` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
 
-* `read:blocks`, `write:blocks`
-* `read:follows`, `write:follows`
-* `read:mutes`, `write:mutes`
+### `admin:read` and `admin:write` {#admin}
 
-### `push` {#push}
+Used for administrative and moderation APIs. Added in Mastodon 2.9.1.
 
-Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.
+Requesting `admin:read` or `admin:write` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
 
-### Admin scopes {#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):
-
-* `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`
+{{< 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 |
-
-| 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 |
+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`.
+
+| 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.

content/en/api/oauth-tokens.md

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