From cb3aa4de10139a25d0a04d788eeb7b50cbd2d4af Mon Sep 17 00:00:00 2001 From: Emelia Smith Date: Thu, 10 Oct 2024 14:44:19 +0200 Subject: [PATCH] Document new OAuth changes for 4.3.0 (#1445) * 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 * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski * 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 Co-authored-by: David Roetzel --- archetypes/methods.md | 2 +- assets/style.scss | 15 ++ content/en/admin/config.md | 7 +- content/en/api/guidelines.md | 4 +- content/en/api/oauth-scopes.md | 231 ++++++++++-------- content/en/api/oauth-tokens.md | 27 ++ content/en/client/authorized.md | 89 ++++--- content/en/client/public.md | 8 +- content/en/client/token.md | 39 ++- content/en/dev/overview.md | 17 +- content/en/entities/Application.md | 63 ++++- content/en/entities/MediaAttachment.md | 4 +- content/en/entities/Search.md | 2 +- content/en/methods/accounts.md | 53 ++-- content/en/methods/admin/accounts.md | 22 +- .../methods/admin/canonical_email_blocks.md | 10 +- content/en/methods/admin/dimensions.md | 2 +- content/en/methods/admin/domain_allows.md | 8 +- content/en/methods/admin/domain_blocks.md | 10 +- .../en/methods/admin/email_domain_blocks.md | 8 +- content/en/methods/admin/ip_blocks.md | 10 +- content/en/methods/admin/measures.md | 2 +- content/en/methods/admin/reports.md | 14 +- content/en/methods/admin/retention.md | 2 +- content/en/methods/admin/trends.md | 6 +- content/en/methods/announcements.md | 8 +- content/en/methods/apps.md | 104 ++++++-- content/en/methods/blocks.md | 2 +- content/en/methods/bookmarks.md | 2 +- content/en/methods/conversations.md | 6 +- content/en/methods/domain_blocks.md | 6 +- content/en/methods/emails.md | 2 +- content/en/methods/endorsements.md | 2 +- content/en/methods/favourites.md | 2 +- content/en/methods/featured_tags.md | 8 +- content/en/methods/filters.md | 50 ++-- content/en/methods/follow_requests.md | 6 +- content/en/methods/followed_tags.md | 2 +- content/en/methods/instance.md | 145 +++++------ content/en/methods/lists.md | 16 +- content/en/methods/markers.md | 4 +- content/en/methods/media.md | 10 +- content/en/methods/mutes.md | 2 +- content/en/methods/notifications.md | 14 +- content/en/methods/oauth.md | 162 +++++++++++- content/en/methods/polls.md | 4 +- content/en/methods/preferences.md | 2 +- content/en/methods/profile.md | 8 +- content/en/methods/proofs.md | 2 +- content/en/methods/push.md | 11 +- content/en/methods/reports.md | 2 +- content/en/methods/scheduled_statuses.md | 8 +- content/en/methods/search.md | 6 +- content/en/methods/statuses.md | 46 ++-- content/en/methods/streaming.md | 41 ++-- content/en/methods/suggestions.md | 8 +- content/en/methods/tags.md | 6 +- content/en/methods/timelines.md | 12 +- content/en/spec/activitypub.md | 2 +- content/en/spec/oauth.md | 59 ++++- i18n/en.toml | 6 + layouts/shortcodes/deprecated.html | 1 + layouts/shortcodes/removed.html | 1 + 63 files changed, 926 insertions(+), 507 deletions(-) create mode 100644 content/en/api/oauth-tokens.md create mode 100644 layouts/shortcodes/deprecated.html create mode 100644 layouts/shortcodes/removed.html diff --git a/archetypes/methods.md b/archetypes/methods.md index ba3ea7f7..9ac9667a 100644 --- a/archetypes/methods.md +++ b/archetypes/methods.md @@ -32,7 +32,7 @@ x.x.x - added ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters diff --git a/assets/style.scss b/assets/style.scss index 566cf643..1696a1fe 100644 --- a/assets/style.scss +++ b/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; diff --git a/content/en/admin/config.md b/content/en/admin/config.md index 8a454238..79152235 100644 --- a/content/en/admin/config.md +++ b/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` diff --git a/content/en/api/guidelines.md b/content/en/api/guidelines.md index e5e43b6c..f981e2bf 100644 --- a/content/en/api/guidelines.md +++ b/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 Link: ; rel="next", ; rel="prev" [ diff --git a/content/en/api/oauth-scopes.md b/content/en/api/oauth-scopes.md index 93512f28..b818dc5e 100644 --- a/content/en/api/oauth-scopes.md +++ b/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.** - -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. +{{}} + +### 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 | \ No newline at end of file +| 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. \ No newline at end of file diff --git a/content/en/api/oauth-tokens.md b/content/en/api/oauth-tokens.md new file mode 100644 index 00000000..8c04f7ff --- /dev/null +++ b/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]({{}}), 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`]({{}}) +- [`POST /api/v1/accounts`]({{}}) + +### User tokens + +In order to create a User token, you must perform a [authorization code grant 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. diff --git a/content/en/client/authorized.md b/content/en/client/authorized.md index 79b18f8f..5e2a9d22 100644 --- a/content/en/client/authorized.md +++ b/content/en/client/authorized.md @@ -9,9 +9,13 @@ menu: ## Scopes explained {#scopes} -When we register our app and when we authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of OAuth scopes. Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope. +When we register our app and when we authorize our user, we need to define what exactly our generated token will have permission to do. This is done through the use of [OAuth Scopes]({{< relref "api/oauth-scopes" >}}). Each API method has an associated scope, and can only be called if the token being used for authorization has been generated with the corresponding scope. -Scopes must be a subset. When we created our app, we specified `read write push` -- we could request all available scopes by specifying `read write push`, but it is a better idea to only request what your app will actually need through granular scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth access level and scope required to call it. +When authorizing a user, the `scope` query parameter must be a subset of those we specified when we created our app. In our ongoing example, we specified `read write push` as our scopes when we created our app, however it is a better idea to only request access to what your app will actually need through [granular scopes]({{< relref "api/oauth-scopes#granular-scopes" >}}). + +See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a full list of scopes. Each API method's documentation will also specify the OAuth [token type]({{< relref "api/oauth-tokens" >}}) and the scopes required to call it. If an endpoint specifies `read:statuses` and you have `read` access, then you will be able to use that endpoint, since scopes are hierarchial. + +{{< page-relref ref="api/oauth-scopes" caption="OAuth Scopes" >}} ## **Example authorization code flow** {#flow} @@ -37,7 +41,13 @@ Note the following: * `client_id` was obtained when registering our application. * `scope` must be a subset of our app's registered scopes. It is a good idea to only request what you need. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information. -* `redirect_uri` is one of the URIs we registered with our app. We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` and can be logged by your request handler. See the response section of the API method documentation for more information on this. +* `redirect_uri` is one of the URIs we registered with our app. + +We are still using "out of band" for this example, which means we will have to manually copy and paste the resulting code, but if you registered your application with a URI that you control, then the code will be returned as a query parameter `code` by your request handler for the redirect URI. See the response section of the API method documentation for more information on this. + +{{< hint style="warning" >}} +Treat the `code` query parameter as if it were a password, you should ensure that it is not logged in request logs. +{{< /hint >}} ### Obtain the token {#token} @@ -56,16 +66,24 @@ curl -X POST \ Note the following: -* `client_id` and `client_secret` were provided in the response text when you registered your application. -* `redirect_uri` must be one of the URIs defined when registering the application. -* We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here. -* The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "client/authorized#authorize-the-user" >}}) step. +- `client_id` and `client_secret` were provided in the response text when you registered your application. +- `redirect_uri` must be one of the URIs defined when registering the application. +- We are requesting a `grant_type` of `authorization_code`, which still defaults to giving us the `read` scope. However, while authorizing our user, we requested a certain `scope` -- pass the exact same value here. +- The `code` can only be used once. If you need to obtain a new token, you will need to have the user authorize again by repeating the above [Authorize the user]({{< relref "client/authorized#authorize-the-user" >}}) step. -The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}): +The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. + +{{< hint style="warning" >}} +Treat the `access_token` as if it were a password. We recommend you encrypt this value when storing in your cache, to prevent accidental credential exposure. +{{< /hint >}} + +To use it in requests, add the HTTP header `Authorization: Bearer ` to any API call that requires OAuth (i.e., one that is not publicly accessible). + +Let's verify that our obtained credentials are working by calling [GET /api/v1/accounts/verify_credentials]({{< relref "methods/accounts#verify_credentials" >}}): ```bash curl \ - -H 'Authorization: Bearer our_access_token_here' \ + -H 'Authorization: Bearer ' \ https://mastodon.example/api/v1/accounts/verify_credentials ``` @@ -77,48 +95,47 @@ With our OAuth token for the authorized user, we can now perform any action as t ### Publish and delete statuses {#statuses} -* See [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}}) for how to create statuses. - * See [/api/v1/media]({{< relref "methods/media" >}}) for creating media attachments. - * See [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses. +- See [POST /api/v1/statuses]({{< relref "methods/statuses#create" >}}) for how to create statuses. + - See [/api/v1/media]({{< relref "methods/media" >}}) for creating media attachments. + - See [/api/v1/scheduled_statuses]({{< relref "methods/scheduled_statuses" >}}) for managing scheduled statuses. ### Interact with timelines {#timelines} -* See [/api/v1/timelines]({{< relref "methods/timelines" >}}) for accessing timelines. -* See [/api/v1/markers]({{< relref "methods/markers" >}}) for saving and loading positions in timelines. -* See [/api/v1/statuses]({{< relref "methods/statuses" >}}) for performing actions on statuses. - * See [/api/v1/polls]({{< relref "methods/polls" >}}) for viewing and voting on polls. -* See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}). -* See [/api/v1/conversations]({{< relref "methods/conversations" >}}) for obtaining direct conversations. -* See [/api/v1/favourites]({{< relref "methods/favourites" >}}) for listing favourites. -* See [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}}) for listing bookmarks. +- See [/api/v1/timelines]({{< relref "methods/timelines" >}}) for accessing timelines. +- See [/api/v1/markers]({{< relref "methods/markers" >}}) for saving and loading positions in timelines. +- See [/api/v1/statuses]({{< relref "methods/statuses" >}}) for performing actions on statuses. + - See [/api/v1/polls]({{< relref "methods/polls" >}}) for viewing and voting on polls. +- See [/api/v1/lists]({{< relref "methods/lists" >}}) for obtaining list IDs to use with [GET /api/v1/timelines/list/:list_id]({{< relref "methods/timelines#list" >}}). +- See [/api/v1/conversations]({{< relref "methods/conversations" >}}) for obtaining direct conversations. +- See [/api/v1/favourites]({{< relref "methods/favourites" >}}) for listing favourites. +- See [/api/v1/bookmarks]({{< relref "methods/bookmarks" >}}) for listing bookmarks. ### Interact with other users {#accounts} -* See [/api/v1/accounts]({{< relref "methods/accounts" >}}) for performing actions on other users. -* See [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests. -* See [/api/v1/mutes]({{< relref "methods/mutes" >}}) for listing mutes. -* See [/api/v1/blocks]({{< relref "methods/blocks" >}}) for listing blocks. +- See [/api/v1/accounts]({{< relref "methods/accounts" >}}) for performing actions on other users. +- See [/api/v1/follow_requests]({{< relref "methods/follow_requests" >}}) for handling follow requests. +- See [/api/v1/mutes]({{< relref "methods/mutes" >}}) for listing mutes. +- See [/api/v1/blocks]({{< relref "methods/blocks" >}}) for listing blocks. ### Receive notifications {#notifications} -* See [/api/v1/notifications]({{< relref "methods/notifications" >}}) for managing a user's notifications. -* See [/api/v1/push]({{< relref "methods/push" >}}) for subscribing to push notifications. +- See [/api/v1/notifications]({{< relref "methods/notifications" >}}) for managing a user's notifications. +- See [/api/v1/push]({{< relref "methods/push" >}}) for subscribing to push notifications. ### Discovery features {#discovery} -* See [/api/v2/search]({{< relref "methods/search#v2" >}}) for querying resources. -* See [/api/v1/suggestions]({{< relref "methods/suggestions" >}}) for suggested accounts to follow. +- See [/api/v2/search]({{< relref "methods/search#v2" >}}) for querying resources. +- See [/api/v1/suggestions]({{< relref "methods/suggestions" >}}) for suggested accounts to follow. ### User safety features {#safety} -* See [/api/v1/filters]({{< relref "methods/filters" >}}) for managing filtered keywords. -* See [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains. -* See [/api/v1/reports]({{< relref "methods/reports" >}}) for creating reports. -* See [/api/v1/admin]({{< relref "methods/admin" >}}) for moderator actions. +- See [/api/v1/filters]({{< relref "methods/filters" >}}) for managing filtered keywords. +- See [/api/v1/domain_blocks]({{< relref "methods/domain_blocks" >}}) for managing blocked domains. +- See [/api/v1/reports]({{< relref "methods/reports" >}}) for creating reports. +- See [/api/v1/admin]({{< relref "methods/admin" >}}) for moderator actions. ### Manage account info {#manage} -* See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts. -* See [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags. -* See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences. - +- See [/api/v1/endorsements]({{< relref "methods/endorsements" >}}) for managing a user profile's featured accounts. +- See [/api/v1/featured_tags]({{< relref "methods/featured_tags" >}}) for managing a user profile's featured hashtags. +- See [/api/v1/preferences]({{< relref "methods/preferences" >}}) for reading user preferences. diff --git a/content/en/client/public.md b/content/en/client/public.md index 3cc4897c..1b87c597 100644 --- a/content/en/client/public.md +++ b/content/en/client/public.md @@ -25,7 +25,13 @@ We can try to request [GET /api/v1/timelines/public]({{< relref "methods/timelin curl https://mastodon.example/api/v1/timelines/public ``` -Wow, that's a lot of text in response! The public timeline returns 20 statuses by default. We can use the `limit` parameter to request less than that. Let's try requesting the same endpoint, but with a limit of 2 this time: +Wow, that's a lot of text in response! The public timeline returns 20 statuses by default. + +{{< hint style="danger" >}} +Some Mastodon servers may disable public access to their timelines via the Admin Settings. If this is the case for your server, then you will receive an error response back. +{{}} + +We can use the `limit` parameter to request less than that. Let's try requesting the same endpoint, but with a limit of 2 this time: ```bash curl https://mastodon.example/api/v1/timelines/public?limit=2 diff --git a/content/en/client/token.md b/content/en/client/token.md index b983c90e..871b4003 100644 --- a/content/en/client/token.md +++ b/content/en/client/token.md @@ -28,10 +28,22 @@ curl -X POST \ In the above example, we specify the client name and website, which will be shown on statuses if applicable. But more importantly, note the following two parameters: -* `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list. -* `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information. +- `redirect_uris` has been set to the "out of band" token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called `redirect_uris` because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list. +- `scopes` allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for more information. -We should see an Application entity returned, but for now, we only care about client_id and client_secret. These values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications. +You can also create applications by POSTing a JSON body to the same endpoint, as documented in [POST /api/v1/apps]({{< relref "methods/apps#create-request-example" >}}). + +{{< hint style="info" >}} +As of Mastodon 4.3.0, you can discover which `scopes` the server supports along with other information by making a request to the [`/.well-known/oauth-authorization-server`]({{< relref "methods/oauth#authorization-server-metadata" >}}) endpoint. +{{< /hint >}} + +We should see a [CredentialApplication]({{< relref "entities/application#CredentialApplication" >}}) entity returned, but for now, we only care about `client_id` and `client_secret`. + +The `client_id` and `client_secret` values will be used to generate access tokens, so they should be cached for later use. See [POST /api/v1/apps]({{< relref "methods/apps#create" >}}) for more details on registering applications. + +{{< hint style="warning" >}} +Treat the `client_id` and `client_secret` properties as if they are passwords. We recommend you encrypt these when storing in your cache, to prevent accidental credential exposure. +{{< /hint >}} ## Example authentication code flow {#flow} @@ -48,21 +60,28 @@ curl -X POST \ Note the following: -* `client_id` and `client_secret` were provided in the response text when you registered your application. -* `redirect_uri` must be one of the URIs defined when registering the application. -* We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope. +- `client_id` and `client_secret` were provided in the response text when you registered your application. +- `redirect_uri` must be one of the URIs defined when registering the application. +- We are requesting a `grant_type` of `client_credentials`, which defaults to giving us the `read` scope. -The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. To use it in requests, add the HTTP header `Authorization: Bearer ...` to any API call that requires OAuth (i.e., one that is not publicly accessible). Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}): +The response of this method is a [Token]({{< relref "entities/token" >}}) entity. We will need the `access_token` value. Once you have the access token, save it in your local cache. + +{{< hint style="warning" >}} +Treat the `access_token` as if it were a password. We recommend you encrypt this value when storing in your cache, to prevent accidental credential exposure. +{{< /hint >}} + +To use it in requests, add the HTTP header `Authorization: Bearer ` to any API call that requires OAuth (i.e., one that is not publicly accessible). + +Let's verify that our obtained credentials are working by calling [GET /api/v1/apps/verify_credentials]({{< relref "methods/apps#verify_credentials" >}}): ```bash curl \ - -H 'Authorization: Bearer our_access_token_here' \ + -H 'Authorization: Bearer ' \ https://mastodon.example/api/v1/apps/verify_credentials ``` -If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "entities/application" >}}) entity. +If we've obtained our token and formatted our request correctly, we should see our details returned to us as an [Application]({{< relref "entities/application" >}}) entity (without the `client_secret` property). ## What we can do with authentication {#methods} With our authenticated client application, we can view relations of an account with [GET /api/v1/accounts/:id/following]({{< relref "methods/accounts#following" >}}) and [GET /api/v1/accounts/:id/followers]({{< relref "methods/accounts#followers" >}}). Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work. - diff --git a/content/en/dev/overview.md b/content/en/dev/overview.md index 64b0759b..2d39c6a0 100644 --- a/content/en/dev/overview.md +++ b/content/en/dev/overview.md @@ -7,7 +7,11 @@ menu: parent: dev --- -Mastodon is a Ruby on Rails application with a React.js front-end. It follows standard practices of those frameworks, so if you are already familiar with Rails or React.js, you will not find any surprises here. + + +Mastodon is a Ruby on Rails application with a React.js front-end. It follows standard practices of those frameworks, so if you are already familiar with Rails or React.js, you will not find any surprises here. The best way of working with Mastodon in a development environment is installing all the dependencies on your system, rather than using Docker or Vagrant. You need Ruby, Node.js, PostgreSQL and Redis, which is a pretty standard set of dependencies for Rails applications. @@ -19,11 +23,10 @@ An “environment” is a set of configuration values intended for a specific us The default value of `RAILS_ENV` is `development`, so you don’t need to set anything extra to run Mastodon in development mode. In fact, all of Mastodon’s configuration has correct defaults for the development environment, so you do not need an `.env` file unless you need to customize something. Here are some of the different behaviours between the development environment and the production environment: -* Ruby code reloads itself when you change it, which means you don’t need to restart the Rails server process to see changes -* All errors you encounter show stack traces in the browser, rather than being hidden behind a generic error page -* Webpack runs continuously and re-compiles JS and CSS assets when you change any of the front-end files, and the pages automatically reload -* Caching is disabled by default -* An admin account with the e-mail `admin@localhost:3000` and password `mastodonadmin` is created automatically during `db:seed` +- Ruby code reloads itself when you change it, which means you don’t need to restart the Rails server process to see changes +- All errors you encounter show stack traces in the browser, rather than being hidden behind a generic error page +- Webpack runs continuously and re-compiles JS and CSS assets when you change any of the front-end files, and the pages automatically reload +- Caching is disabled by default +- An admin account with the e-mail `admin@localhost:3000` and password `mastodonadmin` is created automatically during `db:seed` It should be noted that the Docker configuration distributed with Mastodon is optimized for the production environment, and so is an extremely bad fit for development. The Vagrant configuration, on the other hand, is meant specifically for development and not production use. - diff --git a/content/en/entities/Application.md b/content/en/entities/Application.md index 5ce71c8e..b0b067c5 100644 --- a/content/en/entities/Application.md +++ b/content/en/entities/Application.md @@ -16,9 +16,14 @@ aliases: [ ```json { - "name": "test app", - "website": null, - "vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M=" + "name": "Test Application", + "website": "https://app.example", + "scopes": ["read", "write", "push"], + "redirect_uri": "https://app.example/callback\nhttps://app.example/register", + "redirect_uris": [ + "https://app.example/callback", + "https://app.example/register" + ] } ``` @@ -39,29 +44,63 @@ aliases: [ 0.9.9 - added\ 3.5.1 - this property is now nullable -### `client_id` {{%optional%}} {#client_id} +### `scopes` {#scopes} + +**Description:** The scopes for your application. This is the registered `scopes` string split on whitespace.\ +**Type:** Array of Strings\ +**Version history:**\ +4.3.0 - added + +### `redirect_uris` {#redirect_uris} + +**Description:** The registered redirection URI(s) for your application.\ +**Type:** Array of String (URLs or `"urn:ietf:wg:oauth:2.0:oob"` as values)\ +**Version history:**\ +4.3.0 - added + +### `redirect_uri` {{%deprecated%}} {#redirect_uri} + +**Description:** The registered redirection URI(s) for your application.\ +May contain `\n` characters when multiple redirect URIs are registered.\ +**Type:** String\ +**Version history:**\ +0.0.0 - added\ +4.3.0 - deprecated in favour of [`redirect_uris`]({{< relref "entities/Application#redirect_uris" >}}), since the value of this property is not a well-formed URI when multiple redirect URIs are registered + +### `vapid_key` {{%deprecated%}} {#vapid_key} + +**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "methods/apps#create" >}}). Equivalent to [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) and [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\ +**Type:** String\ +**Version history:**\ +2.8.0 - added\ +4.3.0 - deprecated pending removal, please see [api/v2/instance]({{< relref "methods/Instance#v2">}}) for this value (`configuration.vapid.public_key`) + +## CredentialApplication attributes {#CredentialApplication} + +All [Application](#attributes) attributes and the following: + +### `client_id` {#client_id} **Description:** Client ID key, to be used for obtaining OAuth tokens\ **Type:** String\ **Version history:**\ 0.9.9 - added +4.3.0 - moved to `CredentialApplication` from `Application` -### `client_secret` {{%optional%}} {#client_secret} +### `client_secret` {#client_secret} **Description:** Client secret key, to be used for obtaining OAuth tokens\ **Type:** String\ **Version history:**\ 0.9.9 - added +4.3.0 - moved to `CredentialApplication` from `Application` -## Deprecated attributes +### `client_secret_expires_at` {#client_secret_expires_at} -### `vapid_key` {#vapid_key} - -**Description:** Used for Push Streaming API. Returned with [POST /api/v1/apps]({{< relref "methods/apps#create" >}}). Equivalent to [WebPushSubscription#server_key]({{< relref "entities/WebPushSubscription#server_key" >}}) and [Instance#vapid_public_key]({{< relref "entities/Instance#vapid_public_key" >}})\ +**Description:** When the client secret key will expire at, presently this always returns `0` indicating that OAuth Clients do not expire\ **Type:** String\ **Version history:**\ -2.8.0 - added -4.3.0 - deprecated pending removal +4.3.0 - added ## See also @@ -70,3 +109,5 @@ aliases: [ {{< page-relref ref="entities/Status#application" caption="Status (`application` attribute)" >}} {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/application_serializer.rb" caption="app/serializers/rest/application_serializer.rb" >}} + +{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/credential_application_serializer.rb" caption="app/serializers/rest/credential_application_serializer.rb" >}} diff --git a/content/en/entities/MediaAttachment.md b/content/en/entities/MediaAttachment.md index 525e4b65..2df9369f 100644 --- a/content/en/entities/MediaAttachment.md +++ b/content/en/entities/MediaAttachment.md @@ -223,9 +223,7 @@ More importantly, there may be another topl-level `focus` Hash object on images **Version history:**\ 2.8.1 - added -## Deprecated attributes - -### `text_url` {#text_url} +### `text_url` {{%removed%}} {#text_url} **Description:** A shorter URL for the attachment.\ **Type:** String (URL)\ diff --git a/content/en/entities/Search.md b/content/en/entities/Search.md index bc3ec927..21bead5d 100644 --- a/content/en/entities/Search.md +++ b/content/en/entities/Search.md @@ -109,7 +109,7 @@ Truncated sample search for q=cats limit=2 **Version history:**\ 1.1.0 - added\ 2.4.1 - v1/search deprecated because it returns Array of String. v2/search added which returns Array of Tag.\ -3.0.0 - v1 removed +3.0.0 - v1/search removed ## See also diff --git a/content/en/methods/accounts.md b/content/en/methods/accounts.md index bbf4ec8f..78fa003f 100644 --- a/content/en/methods/accounts.md +++ b/content/en/methods/accounts.md @@ -25,6 +25,8 @@ POST /api/v1/accounts HTTP/1.1 Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox. +A relationship between the OAuth Application and created user account is stored. + **Returns:** [Token]({{< relref "entities/token" >}})\ **OAuth:** App token + `write:accounts`\ **Version history:**\ @@ -37,7 +39,7 @@ Creates a user and account records. Returns an account access token for the app ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -157,16 +159,17 @@ GET /api/v1/accounts/verify_credentials HTTP/1.1 Test to make sure that the user token works. **Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\ -**OAuth**: User token + `read:accounts`\ +**OAuth:** User token + `profile` or `read:accounts`\ **Version history:**\ 0.0.0 - added +4.3.0 - added `profile` scope #### Request ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response @@ -323,7 +326,7 @@ Update the user's display and preferences. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -557,7 +560,7 @@ View information about a profile. ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -746,7 +749,7 @@ id[] ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -832,7 +835,7 @@ Statuses posted to the given account. ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -940,7 +943,7 @@ Accounts which follow the given account, if network is not hidden by the account ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -1046,7 +1049,7 @@ Accounts which the given account is following, if network is not hidden by the a ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -1149,7 +1152,7 @@ Tags featured by this account. ##### Headers Authorization -: Provide this header with `Bearer ` to gain authorized access to this API method. +: Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1189,7 +1192,7 @@ User lists that you have added this account to. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1280,7 +1283,7 @@ Follow the given account. Can also be used to update whether to show reblogs or ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -1360,7 +1363,7 @@ Unfollow the given account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1428,7 +1431,7 @@ Remove the given account from your followers. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1497,7 +1500,7 @@ Block the given account. Clients should filter statuses from this account if rec ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1566,7 +1569,7 @@ Unblock the given account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1636,7 +1639,7 @@ Mute the given account. Clients should filter statuses and notifications from th ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -1713,7 +1716,7 @@ Unmute the given account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1782,7 +1785,7 @@ Add the given account to the user's featured profiles. (Featured profiles are cu ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1880,7 +1883,7 @@ Remove the given account from the user's featured profiles. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -1948,7 +1951,7 @@ Sets a private note on a user. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -2038,7 +2041,7 @@ Find out whether a given account is followed, blocked, muted, etc. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -2125,7 +2128,7 @@ Obtain a list of all accounts that follow a given account, filtered for accounts ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -2204,7 +2207,7 @@ Search for matching accounts by username or display name. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -2327,7 +2330,7 @@ Username or address does not map to an account --- -## (DEPRECATED) Identity proofs {#identity_proofs} +## Identity proofs {{%deprecated%}} {#identity_proofs} ```http GET /api/v1/accounts/:id/identity_proofs HTTP/1.1 diff --git a/content/en/methods/admin/accounts.md b/content/en/methods/admin/accounts.md index e53c73ed..c2cd2fb5 100644 --- a/content/en/methods/admin/accounts.md +++ b/content/en/methods/admin/accounts.md @@ -37,7 +37,7 @@ View all accounts, optionally matching certain criteria for filtering, up to 100 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -199,7 +199,7 @@ View all accounts, optionally matching certain criteria for filtering, up to 100 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -331,7 +331,7 @@ View admin-level information about the given account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -427,7 +427,7 @@ Approve the given local account if it is currently pending approval. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -493,7 +493,7 @@ Reject the given local account if it is currently pending approval. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -597,7 +597,7 @@ Permanently delete data for a suspended account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -704,7 +704,7 @@ Perform an action against an account and log this action in the moderation histo ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -789,7 +789,7 @@ Re-enable a local account whose login is currently disabled. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -855,7 +855,7 @@ Unsilence an account if it is currently silenced. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -921,7 +921,7 @@ Unsuspend a currently suspended account. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -987,7 +987,7 @@ Stops marking an account's posts as sensitive, if it was previously flagged as s ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/canonical_email_blocks.md b/content/en/methods/admin/canonical_email_blocks.md index cdf44a7d..d4e5ecd1 100644 --- a/content/en/methods/admin/canonical_email_blocks.md +++ b/content/en/methods/admin/canonical_email_blocks.md @@ -33,7 +33,7 @@ GET /api/v1/admin/canonical_email_blocks HTTP/1.1 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -102,7 +102,7 @@ GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -155,7 +155,7 @@ Canoniocalize and hash an email address. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -209,7 +209,7 @@ POST /api/v1/admin/canonical_email_blocks HTTP/1.1 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -275,7 +275,7 @@ DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/dimensions.md b/content/en/methods/admin/dimensions.md index 06f813b1..7e5e2ef9 100644 --- a/content/en/methods/admin/dimensions.md +++ b/content/en/methods/admin/dimensions.md @@ -36,7 +36,7 @@ Obtain information about popularity of certain accounts, servers, languages, etc ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters diff --git a/content/en/methods/admin/domain_allows.md b/content/en/methods/admin/domain_allows.md index c643cbba..ff042c8b 100644 --- a/content/en/methods/admin/domain_allows.md +++ b/content/en/methods/admin/domain_allows.md @@ -35,7 +35,7 @@ Show information about all allowed domains. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -109,7 +109,7 @@ Show information about a single allowed domain. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -163,7 +163,7 @@ Add a domain to the list of domains allowed to federate, to be used when the ins ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -229,7 +229,7 @@ Delete a domain from the allowed domains list. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/domain_blocks.md b/content/en/methods/admin/domain_blocks.md index bba8fb5c..9d3f5820 100644 --- a/content/en/methods/admin/domain_blocks.md +++ b/content/en/methods/admin/domain_blocks.md @@ -35,7 +35,7 @@ Show information about all blocked domains. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -112,7 +112,7 @@ Show information about a single blocked domain. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -173,7 +173,7 @@ Add a domain to the list of domains blocked from federating. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -286,7 +286,7 @@ Change parameters for an existing domain block. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -368,7 +368,7 @@ Lift a block against a domain. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/email_domain_blocks.md b/content/en/methods/admin/email_domain_blocks.md index db672731..808b5ac1 100644 --- a/content/en/methods/admin/email_domain_blocks.md +++ b/content/en/methods/admin/email_domain_blocks.md @@ -35,7 +35,7 @@ Show information about all email domains blocked from signing up. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -136,7 +136,7 @@ Show information about a single email domain that is blocked from signups. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -227,7 +227,7 @@ Add a domain to the list of email domains blocked from signups. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -338,7 +338,7 @@ Lift a block against an email domain. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/ip_blocks.md b/content/en/methods/admin/ip_blocks.md index 3fea61fb..7de9219b 100644 --- a/content/en/methods/admin/ip_blocks.md +++ b/content/en/methods/admin/ip_blocks.md @@ -35,7 +35,7 @@ Show information about all blocked IP ranges. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -109,7 +109,7 @@ Show information about a single IP block. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -166,7 +166,7 @@ Add an IP address range to the list of IP blocks. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -244,7 +244,7 @@ Change parameters for an existing IP block. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -312,7 +312,7 @@ Lift a block against an IP range. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/measures.md b/content/en/methods/admin/measures.md index adcf4793..3f6a2475 100644 --- a/content/en/methods/admin/measures.md +++ b/content/en/methods/admin/measures.md @@ -36,7 +36,7 @@ Obtain statistical measures for your server. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters diff --git a/content/en/methods/admin/reports.md b/content/en/methods/admin/reports.md index 669a5036..d3bdc76e 100644 --- a/content/en/methods/admin/reports.md +++ b/content/en/methods/admin/reports.md @@ -36,7 +36,7 @@ View information about all reports. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Query parameters @@ -153,7 +153,7 @@ GET /api/v1/admin/reports/:id HTTP/1.1 ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -253,7 +253,7 @@ Change metadata for a report. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters @@ -316,7 +316,7 @@ Claim the handling of this report to yourself. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -391,7 +391,7 @@ Unassign a report so that someone else can claim it. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -453,7 +453,7 @@ Mark a report as resolved with no further action taken. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -510,7 +510,7 @@ Reopen a currently closed report, if it is closed. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/admin/retention.md b/content/en/methods/admin/retention.md index baf55ddd..c07dfa0f 100644 --- a/content/en/methods/admin/retention.md +++ b/content/en/methods/admin/retention.md @@ -36,7 +36,7 @@ Generate a retention data report for a given time period and bucket. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. ##### Form data parameters diff --git a/content/en/methods/admin/trends.md b/content/en/methods/admin/trends.md index 957fd45c..3b9d88fa 100644 --- a/content/en/methods/admin/trends.md +++ b/content/en/methods/admin/trends.md @@ -35,7 +35,7 @@ Links that have been shared more than others, including unapproved and unreviewe ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -128,7 +128,7 @@ Statuses that have been interacted with more than others, including unapproved a ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -187,7 +187,7 @@ Tags that are being used more frequently within the past week, including unappro ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/announcements.md b/content/en/methods/announcements.md index 6039f9ee..379d9046 100644 --- a/content/en/methods/announcements.md +++ b/content/en/methods/announcements.md @@ -36,7 +36,7 @@ See all currently active announcements set by admins. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -125,7 +125,7 @@ Allows a user to mark the announcement as read. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -181,7 +181,7 @@ React to an announcement with an emoji. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK @@ -246,7 +246,7 @@ Undo a react emoji to an announcement. ##### Headers Authorization -: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. +: {{}} Provide this header with `Bearer ` to gain authorized access to this API method. #### Response ##### 200: OK diff --git a/content/en/methods/apps.md b/content/en/methods/apps.md index d1dd5b26..215052ce 100644 --- a/content/en/methods/apps.md +++ b/content/en/methods/apps.md @@ -7,10 +7,7 @@ menu: name: apps parent: methods identifier: methods-apps -aliases: [ - "/methods/apps", - "/api/methods/apps", -] +aliases: ["/methods/apps", "/api/methods/apps"] ---