mirror of
https://github.com/mastodon/documentation
synced 2025-04-11 22:56:17 +02:00
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 <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Add deprecated and removed shortcode labels * Use deprecated and removed shortcodes * Improve OAuth documentation * More OAuth documentation improvements * Correct streaming API documentation after 4.2.0 changes * Add note about improved Push Subscription API validation in 4.3.0 * Fix inconsistent OAuth label formatting * Add note that there is a relationship between Accounts and the Application used to create them * Add note that application registration endpoint also supports JSON bodies * Be consistent in the formatting of placeholder values for Bearer tokens * code review changes * Slight changes in wording * Add documentation for PKCE * Removal of crypto oauth scope * Cross-link authorization's scope with the OAuth Scopes documentation * Update content/en/methods/oauth.md * Update content/en/api/oauth-scopes.md --------- Co-authored-by: Matt Jankowski <matt@jankowski.online> Co-authored-by: David Roetzel <david@roetzel.de>
This commit is contained in:
Emelia Smith
GitHub
parent
c99799ac3e
commit
cb3aa4de10
@ -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
|
||||
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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`
|
||||
|
||||
|
||||
@ -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"
|
||||
[
|
||||
|
||||
@ -9,130 +9,161 @@ menu:
|
||||
|
||||
## OAuth Scopes
|
||||
|
||||
The API is divided up into access scopes. The scopes are hierarchical, i.e. if you have access to `read`, you automatically have access to `read:accounts`. **It is recommended that you request as little as possible for your application.**
|
||||
|
||||
Multiple scopes can be requested at the same time: During app creation with the `scopes` param, and during the authorization phase with the `scope` query param (space-separate the scopes).
|
||||
The API access is divided up into several OAuth scopes, these limit what an API client can do, based on the registered and requested scopes for the [Access Token]({{< relref "api/oauth-tokens" >}}). The scopes in Mastodon are hierarchical, for example, if you request the `read` scope, you automatically have access to `read:accounts`, however **we recommend that you request the most limited scopes as possible for your application**, i.e., if you only need read access to lists and the current user profile, then you should use `profile read:lists` as your scopes instead of `read`.
|
||||
|
||||
{{< hint style="info" >}}
|
||||
Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate `scopes`.
|
||||
To just retrieve the details of the currently authenticated user, use the `profile` scope, which can only access the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) endpoint.\
|
||||
This scope was added in Mastodon 4.3, so we recommend using the "Discovering OAuth Scopes supported by a given Mastodon Server" guidance below when using this scope.
|
||||
{{</ hint >}}
|
||||
|
||||
### Discovering OAuth Scopes supported by a given Mastodon Server
|
||||
|
||||
As of Mastodon 4.3.0, support for [RFC 8414](https://tools.ietf.org/html/rfc8414)'s `GET /.well-known/oauth-authorization-server` endpoint was added, allowing you to discover the scopes supported by the Mastodon server (as well as other OAuth related information such as the endpoints and grant flows).
|
||||
|
||||
We recommended using this endpoint in order to support multiple versions of Mastodon for your OAuth Application.
|
||||
|
||||
If you make a request to the `GET /.well-known/oauth-authorization-server` endpoint, and it returns a 404, then you can assume that the Mastodon server is running a version older than 4.3, in which case you'll need to look at the specific scopes your application needs and what the lowest common scopes are for the version range of Mastodon that you wish to support.
|
||||
|
||||
{{< hint style="info" >}}
|
||||
**Example:** You want to use the `profile` scope, but also want to support older Mastodon servers that don't have that scope and would need `read:accounts` instead. You could discover whether a server supports that scope by making a request this endpoint.
|
||||
{{< /hint >}}
|
||||
|
||||
If you do not specify a `scope` in your authorization request, or a `scopes` in your app creation request, the resulting access token/app will default to `read` access.
|
||||
{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}}
|
||||
|
||||
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise, authorization will fail.
|
||||
### Multiple scopes can be requested at the same time
|
||||
|
||||
During application creation you can specify multiple space-separated scopes with the `scopes` parameter. During the authorization phase you can do the same with the `scope` query parameter.
|
||||
|
||||
{{< hint style="danger" >}}
|
||||
The set of scopes saved during application creation must include all the scopes that you will request in the authorization request, otherwise, authorization will fail.
|
||||
{{< /hint >}}
|
||||
|
||||
{{< hint style="info" >}}
|
||||
Mind the `scope` vs `scopes` difference. This is because `scope` is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate `scopes` name instead.
|
||||
{{< /hint >}}
|
||||
|
||||
If you do not specify `scope` in your authorization request, or `scopes` in your application creation request, the resulting access token/app will be assigned the default scope. This is currently `read` as of Mastodon 4.3, but is subject to change in the future.
|
||||
|
||||
{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}}
|
||||
|
||||
### Version history {#versions}
|
||||
|
||||
- 0.9.0 - read, write, follow
|
||||
- 2.4.0 - push
|
||||
- 2.4.3 - granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929)
|
||||
- 2.6.0 - read:reports deprecated (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
|
||||
- 2.6.0 - write:conversations added [#9009](https://github.com/mastodon/mastodon/pull/9009)
|
||||
- 2.9.1 - Admin scopes added [#9387](https://github.com/mastodon/mastodon/pull/9387)
|
||||
- 3.1.0 - Bookmark scopes added [#7107](https://github.com/mastodon/mastodon/pull/7107)
|
||||
- 0.9.0 - Added read, write, follow scopes
|
||||
- 2.4.0 - Added push scope for push notifications
|
||||
- 2.4.3 - Added granular scopes [#7929](https://github.com/mastodon/mastodon/pull/7929)
|
||||
- 2.6.0 - Deprecated `read:reports` (unused stub) [#8736/adcf23f](https://github.com/mastodon/mastodon/pull/8736/commits/adcf23f1d00c8ff6877ca2ee2af258f326ae4e1f)
|
||||
- 2.6.0 - Added `write:conversations` [#9009](https://github.com/mastodon/mastodon/pull/9009)
|
||||
- 2.9.1 - Added administrative and moderation scopes [#9387](https://github.com/mastodon/mastodon/pull/9387)
|
||||
- 3.1.0 - Added bookmark scopes [#7107](https://github.com/mastodon/mastodon/pull/7107)
|
||||
- 3.5.0 - Deprecated `follow` scope in favour of granular scopes [#17678](https://github.com/mastodon/mastodon/pull/17678)
|
||||
- 4.1.0 - Added admin scopes for blocks and allows [#20918](https://github.com/mastodon/mastodon/pull/20918)
|
||||
- 4.3.0 - Added `profile` scope to obtain only information about the currently authenticated user [#29087](https://github.com/mastodon/mastodon/pull/29087), [#30357](https://github.com/mastodon/mastodon/pull/30357)
|
||||
|
||||
## List of scopes
|
||||
## List of high-level scopes
|
||||
|
||||
We recommend that you use the [granular scopes](#granular-scopes) shown in the right column of the table below, instead of using the following scopes:
|
||||
|
||||
- `read`
|
||||
- `write`
|
||||
- `follow` {{%deprecated%}}
|
||||
- `admin:read`
|
||||
- `admin:write`
|
||||
|
||||
When only the information about the currently authenticated user is required, use the `profile` scope.
|
||||
|
||||
### `profile` {#profile}
|
||||
|
||||
Grants access only to the [`GET /api/v1/accounts/verify_credentials`]({{< relref "methods/accounts#verify_credentials" >}}) endpoint. Allowing you to retrieve information about only the currently authenticated user.
|
||||
|
||||
### `read` {#read}
|
||||
|
||||
Grants access to read data. Requesting `read` will also grant child scopes shown in the left column of the table below.
|
||||
|
||||
* `read`
|
||||
* `read:accounts`
|
||||
* `read:blocks`
|
||||
* `read:bookmarks`
|
||||
* `read:favourites`
|
||||
* `read:filters`
|
||||
* `read:follows`
|
||||
* `read:lists`
|
||||
* `read:mutes`
|
||||
* `read:notifications`
|
||||
* `read:search`
|
||||
* `read:statuses`
|
||||
Grants access to read data, including other users. Requesting `read` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
|
||||
|
||||
### `write` {#write}
|
||||
|
||||
Grants access to write data. Requesting `write` will also grant child scopes shown in the right column of the table below.
|
||||
|
||||
* `write`
|
||||
* `write:accounts`
|
||||
* `write:blocks`
|
||||
* `write:bookmarks`
|
||||
* `write:conversations`
|
||||
* `write:favourites`
|
||||
* `write:filters`
|
||||
* `write:follows`
|
||||
* `write:lists`
|
||||
* `write:media`
|
||||
* `write:mutes`
|
||||
* `write:notifications`
|
||||
* `write:reports`
|
||||
* `write:statuses`
|
||||
|
||||
### `follow` {#follow}
|
||||
|
||||
{{< hint style="danger" >}}
|
||||
**Deprecated**\
|
||||
This scope has been deprecated in 3.5.0 and newer. You should instead request the child scopes individually, or request read/write permission as needed.
|
||||
{{< /hint >}}
|
||||
|
||||
Grants access to manage relationships. Requesting `follow` will also grant the following child scopes, shown in bold in the table:
|
||||
|
||||
* `read:blocks`, `write:blocks`
|
||||
* `read:follows`, `write:follows`
|
||||
* `read:mutes`, `write:mutes`
|
||||
Grants access to write data. Requesting `write` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
|
||||
|
||||
### `push` {#push}
|
||||
|
||||
Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.
|
||||
|
||||
### Admin scopes {#admin}
|
||||
### `follow` {#follow}
|
||||
|
||||
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular `admin` scope):
|
||||
{{< hint style="danger" >}}
|
||||
**Deprecated**\
|
||||
This scope has been deprecated in 3.5.0 and newer. You should instead request the [granular scopes](#granular-scopes) individually, or request `read`/`write` scopes as needed.
|
||||
{{< /hint >}}
|
||||
|
||||
* `admin:read`
|
||||
* `admin:read:accounts`
|
||||
* `admin:read:reports`
|
||||
* `admin:read:domain_allows`
|
||||
* `admin:read:domain_blocks`
|
||||
* `admin:read:ip_blocks`
|
||||
* `admin:read:email_domain_blocks`
|
||||
* `admin:read:canonical_email_blocks`
|
||||
* `admin:write`
|
||||
* `admin:write:accounts`
|
||||
* `admin:write:reports`
|
||||
* `admin:write:domain_allows`
|
||||
* `admin:write:domain_blocks`
|
||||
* `admin:write:ip_blocks`
|
||||
* `admin:write:email_domain_blocks`
|
||||
* `admin:write:canonical_email_blocks`
|
||||
Grants access to manage relationships. Requesting `follow` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
|
||||
|
||||
### `admin:read` and `admin:write` {#admin}
|
||||
|
||||
Used for administrative and moderation APIs. Added in Mastodon 2.9.1.
|
||||
|
||||
Requesting `admin:read` or `admin:write` will also grant [granular scopes](#granular-scopes) shown in the right column of the table below.
|
||||
|
||||
{{< hint style="info" >}}
|
||||
Note that there is no singular `admin` scope available.
|
||||
{{< /hint >}}
|
||||
|
||||
## Granular scopes {#granular}
|
||||
|
||||
| read | write |
|
||||
| :--- | :--- |
|
||||
| read:accounts | write:accounts |
|
||||
| **read:blocks** | **write:blocks** |
|
||||
| read:bookmarks | write:bookmarks |
|
||||
| | write:conversations |
|
||||
| read:favourites | write:favourites |
|
||||
| read:filters | write:filters |
|
||||
| **read:follows** | **write:follows** |
|
||||
| read:lists | write:lists |
|
||||
| | write:media |
|
||||
| **read:mutes** | **write:mutes** |
|
||||
| read:notifications | write:notifications |
|
||||
| | write:reports |
|
||||
| read:search | |
|
||||
| read:statuses | write:statuses |
|
||||
It is recommended that you make use of granular scopes, unless you really need full access to everything by using a `scope` of `read write follow push`.
|
||||
|
||||
| admin:read | admin:write |
|
||||
| :--- | :--- |
|
||||
| admin:read:accounts | admin:write:accounts |
|
||||
| admin:read:reports | admin:write:reports |
|
||||
| admin:read:domain_allows | admin:write:domain_allows |
|
||||
| admin:read:domain_blocks | admin:write:domain_blocks |
|
||||
| admin:read:ip_blocks | admin:write:ip_blocks |
|
||||
| admin:read:email_domain_blocks | admin:write:email_domain_blocks |
|
||||
| admin:read:canonical_email_blocks | admin:write:canonical_email_blocks |
|
||||
| Scope | Granular Scopes |
|
||||
| :------------------------ | :----------------------------------- |
|
||||
| `profile` | |
|
||||
| `push` | |
|
||||
| `read` | |
|
||||
| | `read:accounts` |
|
||||
| | `read:blocks` |
|
||||
| | `read:bookmarks` |
|
||||
| | `read:favourites` |
|
||||
| | `read:filters` |
|
||||
| | `read:follows` |
|
||||
| | `read:lists` |
|
||||
| | `read:mutes` |
|
||||
| | `read:notifications` |
|
||||
| | `read:search` |
|
||||
| | `read:statuses` |
|
||||
| `write` | |
|
||||
| | `write:accounts` |
|
||||
| | `write:blocks` |
|
||||
| | `write:bookmarks` |
|
||||
| | `write:conversations` |
|
||||
| | `write:favourites` |
|
||||
| | `write:filters` |
|
||||
| | `write:follows` |
|
||||
| | `write:lists` |
|
||||
| | `write:media` |
|
||||
| | `write:mutes` |
|
||||
| | `write:notifications` |
|
||||
| | `write:reports` |
|
||||
| | `write:statuses` |
|
||||
| `follow` {{%deprecated%}} | |
|
||||
| | `read:follows` |
|
||||
| | `write:follows` |
|
||||
| | `read:blocks` |
|
||||
| | `write:blocks` |
|
||||
| | `read:mutes` |
|
||||
| | `write:mutes` |
|
||||
| `admin:read` | |
|
||||
| | `admin:read:accounts` |
|
||||
| | `admin:read:reports` |
|
||||
| | `admin:read:domain_allows` |
|
||||
| | `admin:read:domain_blocks` |
|
||||
| | `admin:read:ip_blocks` |
|
||||
| | `admin:read:email_domain_blocks` |
|
||||
| | `admin:read:canonical_email_blocks` |
|
||||
| `admin:write` | |
|
||||
| | `admin:write:accounts` |
|
||||
| | `admin:write:reports` |
|
||||
| | `admin:write:domain_allows` |
|
||||
| | `admin:write:domain_blocks` |
|
||||
| | `admin:write:ip_blocks` |
|
||||
| | `admin:write:email_domain_blocks` |
|
||||
| | `admin:write:canonical_email_blocks` |
|
||||
|
||||
## Removed scopes {#removed}
|
||||
|
||||
* Mastodon versions from 3.2.0 to 4.3.0 did support a `crypto` scope for end-to-end encryption APIs, however, this functionality was never documented nor fully implemented, and has been removed as of version 4.3.0. Any applications registered with that scope will have the scope removed when the server is upgraded to 4.3.0 and above.
|
||||
27
content/en/api/oauth-tokens.md
Normal file
27
content/en/api/oauth-tokens.md
Normal file
@ -0,0 +1,27 @@
|
||||
---
|
||||
title: OAuth Tokens
|
||||
description: Defining what token types are used throughout this documentation
|
||||
menu:
|
||||
docs:
|
||||
weight: 15
|
||||
parent: api
|
||||
---
|
||||
|
||||
## OAuth Tokens
|
||||
|
||||
Mastodon supports two different types of OAuth Tokens: App tokens and User tokens. Throughout this documentation you will see these token types referenced in the `OAuth` field for API endpoints.
|
||||
|
||||
The `OAuth` field also references Public, in which case no OAuth access token needs to be supplied to access the API endpoint.
|
||||
|
||||
### App tokens
|
||||
|
||||
In order to receive an App token, you must perform a [client credentials grant flow]({{<relref "client/token#flow" >}}), which gives you a token that can be used to interact with the API on behalf of the OAuth Application. Currently the only API endpoints that accepts this token type are:
|
||||
|
||||
- [`GET /api/v1/apps/verify_credentials`]({{<relref "methods/apps#verify_credentials" >}})
|
||||
- [`POST /api/v1/accounts`]({{<relref "/methods/accounts#create" >}})
|
||||
|
||||
### User tokens
|
||||
|
||||
In order to create a User token, you must perform a [authorization code grant flow]({{<relref "client/authorized#flow">}}), which gives you an access token that is associated with the user who approves the access grant request.
|
||||
|
||||
Many Mastodon APIs require User tokens and specific scopes to access them.
|
||||
@ -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 <access_token>` 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 <access_token>' \
|
||||
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.
|
||||
|
||||
@ -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.
|
||||
{{</ hint >}}
|
||||
|
||||
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
|
||||
|
||||
@ -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 <access_token>` 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 <access_token>' \
|
||||
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.
|
||||
|
||||
|
||||
@ -7,6 +7,10 @@ menu:
|
||||
parent: dev
|
||||
---
|
||||
|
||||
<style>
|
||||
#TableOfContents {display: none}
|
||||
</style>
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -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" >}}
|
||||
|
||||
@ -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)\
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
: {{<required>}} Provide this header with `Bearer <app token>` to gain authorized access to this API method.
|
||||
: {{<required>}} Provide this header with `Bearer <app_token>` 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
|
||||
: {{<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.
|
||||
|
||||
#### Response
|
||||
|
||||
@ -323,7 +326,7 @@ Update the user's display and preferences.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -557,7 +560,7 @@ View information about a profile.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -746,7 +749,7 @@ id[]
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` 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 <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` 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 <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` 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 <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` 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 <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` 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
|
||||
: {{<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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1280,7 +1283,7 @@ Follow the given account. Can also be used to update whether to show reblogs or
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1360,7 +1363,7 @@ Unfollow the given account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1428,7 +1431,7 @@ Remove the given account from your followers.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1497,7 +1500,7 @@ Block the given account. Clients should filter statuses from this account if rec
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1566,7 +1569,7 @@ Unblock the given account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1636,7 +1639,7 @@ Mute the given account. Clients should filter statuses and notifications from th
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1713,7 +1716,7 @@ Unmute the given account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1782,7 +1785,7 @@ Add the given account to the user's featured profiles. (Featured profiles are cu
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1880,7 +1883,7 @@ Remove the given account from the user's featured profiles.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1948,7 +1951,7 @@ Sets a private note on a user.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -2038,7 +2041,7 @@ Find out whether a given account is followed, blocked, muted, etc.
|
||||
##### 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
|
||||
|
||||
@ -2125,7 +2128,7 @@ Obtain a list of all accounts that follow a given account, filtered for accounts
|
||||
##### 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
|
||||
|
||||
@ -2204,7 +2207,7 @@ Search for matching accounts by username or display name.
|
||||
##### 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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -37,7 +37,7 @@ View all accounts, optionally matching certain criteria for filtering, up to 100
|
||||
##### 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
|
||||
|
||||
@ -199,7 +199,7 @@ View all accounts, optionally matching certain criteria for filtering, up to 100
|
||||
##### 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
|
||||
|
||||
@ -331,7 +331,7 @@ View admin-level information about the given account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -427,7 +427,7 @@ Approve the given local account if it is currently pending approval.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -493,7 +493,7 @@ Reject the given local account if it is currently pending approval.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -597,7 +597,7 @@ Permanently delete data for a suspended account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -704,7 +704,7 @@ Perform an action against an account and log this action in the moderation histo
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -789,7 +789,7 @@ Re-enable a local account whose login is currently disabled.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -855,7 +855,7 @@ Unsilence an account if it is currently silenced.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -921,7 +921,7 @@ Unsuspend a currently suspended account.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -987,7 +987,7 @@ Stops marking an account's posts as sensitive, if it was previously flagged as s
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -33,7 +33,7 @@ GET /api/v1/admin/canonical_email_blocks HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -102,7 +102,7 @@ GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -155,7 +155,7 @@ Canoniocalize and hash an email address.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -209,7 +209,7 @@ POST /api/v1/admin/canonical_email_blocks HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -275,7 +275,7 @@ DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -36,7 +36,7 @@ Obtain information about popularity of certain accounts, servers, languages, etc
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ Show information about all allowed domains.
|
||||
##### 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
|
||||
|
||||
@ -109,7 +109,7 @@ Show information about a single allowed domain.
|
||||
##### 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.
|
||||
|
||||
#### 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
|
||||
: {{<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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -229,7 +229,7 @@ Delete a domain from the allowed domains list.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -35,7 +35,7 @@ Show information about all blocked domains.
|
||||
##### 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
|
||||
|
||||
@ -112,7 +112,7 @@ Show information about a single blocked domain.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -173,7 +173,7 @@ Add a domain to the list of domains blocked from federating.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -286,7 +286,7 @@ Change parameters for an existing domain block.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -368,7 +368,7 @@ Lift a block against a domain.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -35,7 +35,7 @@ Show information about all email domains blocked from signing up.
|
||||
##### 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
|
||||
|
||||
@ -136,7 +136,7 @@ Show information about a single email domain that is blocked from signups.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -227,7 +227,7 @@ Add a domain to the list of email domains blocked from signups.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -338,7 +338,7 @@ Lift a block against an email domain.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -35,7 +35,7 @@ Show information about all blocked IP ranges.
|
||||
##### 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
|
||||
|
||||
@ -109,7 +109,7 @@ Show information about a single IP block.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -166,7 +166,7 @@ Add an IP address range to the list of IP blocks.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -244,7 +244,7 @@ Change parameters for an existing IP block.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -312,7 +312,7 @@ Lift a block against an IP range.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -36,7 +36,7 @@ Obtain statistical measures for your server.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ View information about all reports.
|
||||
##### 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
|
||||
|
||||
@ -153,7 +153,7 @@ GET /api/v1/admin/reports/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -253,7 +253,7 @@ Change metadata for a report.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -316,7 +316,7 @@ Claim the handling of this report to yourself.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -391,7 +391,7 @@ Unassign a report so that someone else can claim it.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -453,7 +453,7 @@ Mark a report as resolved with no further action taken.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -510,7 +510,7 @@ Reopen a currently closed report, if it is closed.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -36,7 +36,7 @@ Generate a retention data report for a given time period and bucket.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ Links that have been shared more than others, including unapproved and unreviewe
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -128,7 +128,7 @@ Statuses that have been interacted with more than others, including unapproved a
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -187,7 +187,7 @@ Tags that are being used more frequently within the past week, including unappro
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -36,7 +36,7 @@ See all currently active announcements set by admins.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -125,7 +125,7 @@ Allows a user to mark the announcement as read.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -181,7 +181,7 @@ React to an announcement with an emoji.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -246,7 +246,7 @@ Undo a react emoji to an announcement.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -7,10 +7,7 @@ menu:
|
||||
name: apps
|
||||
parent: methods
|
||||
identifier: methods-apps
|
||||
aliases: [
|
||||
"/methods/apps",
|
||||
"/api/methods/apps",
|
||||
]
|
||||
aliases: ["/methods/apps", "/api/methods/apps"]
|
||||
---
|
||||
|
||||
<style>
|
||||
@ -25,20 +22,53 @@ POST /api/v1/apps HTTP/1.1
|
||||
|
||||
Create a new application to obtain OAuth2 credentials.
|
||||
|
||||
**Returns:** [Application]({{< relref "entities/Application" >}})\
|
||||
{{< hint style="danger" >}}
|
||||
In Mastodon prior to 4.3, OAuth Applications could be "vacuumed" and removed from the database under certain conditions, meaning your Application's `client_id` and `client_secret` would not be recognised by the Mastodon server.\
|
||||
This automated removal of applications was removed in Mastodon 4.3\
|
||||
\
|
||||
A workaround for Mastodon versions older than 4.3 was to register your application, and then immediately request a [Client Credential]({{< relref "client/Token#flow" >}}) token, which would permanently ensure your application always had an active access token and would not be removed.
|
||||
{{< /hint >}}
|
||||
|
||||
{{< hint style="info" >}}
|
||||
At present, Mastodon only supports provisioning confidential clients, i.e., you will always receive a `client_secret` and `client_secret_expires_at` attributes in the [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}}) entity.\
|
||||
\
|
||||
For more information see: [OAuth 2 client types]({{< relref "spec/oauth#client-types" >}})
|
||||
{{< /hint >}}
|
||||
|
||||
**Returns:** [CredentialApplication]({{< relref "entities/Application#CredentialApplication" >}})\
|
||||
**OAuth:** Public\
|
||||
**Version history:**\
|
||||
0.0.0 - added\
|
||||
2.7.2 - now returns `vapid_key`
|
||||
2.7.2 - now returns `vapid_key`\
|
||||
4.3.0 - deprecated `vapid_key`, please see [api/v2/instance]({{< relref "methods/Instance#v2">}})\
|
||||
4.3.0 - added support for multiple `redirect_uris` in Form data parameters\
|
||||
4.3.0 - added `redirect_uris` response property\
|
||||
4.3.0 - deprecated `redirect_uri` response property, since this can be a non-URI if multiple `redirect_uris` are registered, use `redirect_uris` instead\
|
||||
4.3.0 - changed entity type from [Application]({{< relref "entities/Application">}}) to [CredentialApplication]({{< relref "entities/Application#CredentialApplication">}})
|
||||
|
||||
#### Request {#create-request-example}
|
||||
|
||||
Example request:
|
||||
|
||||
```
|
||||
POST /api/v1/apps HTTP/1.1
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"client_name": "Test Application",
|
||||
"redirect_uris": ["https://app.example/callback", "https://app.example/register"],
|
||||
"scopes": "read write push",
|
||||
"website": "https://app.example"
|
||||
}
|
||||
```
|
||||
|
||||
#### Request
|
||||
##### Form data parameters
|
||||
|
||||
client_name
|
||||
: {{<required>}} String. A name for your application
|
||||
|
||||
redirect_uris
|
||||
: {{<required>}} String. Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.
|
||||
: {{<required>}} String or Array of Strings. Where the user should be redirected after authorization. To display the authorization code to the user instead of redirecting to a web page, use `urn:ietf:wg:oauth:2.0:oob` in this parameter.
|
||||
|
||||
scopes
|
||||
: String. Space separated list of scopes. If none is provided, defaults to `read`. See [OAuth Scopes]({{< relref "api/oauth-scopes" >}}) for a list of possible scopes.
|
||||
@ -47,22 +77,50 @@ website
|
||||
: String. A URL to the homepage of your app
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
Store the `client_id` and `client_secret` in your cache, as these will be used to obtain OAuth tokens.
|
||||
|
||||
{{< 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 credential exposure.
|
||||
{{< /hint >}}
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "563419",
|
||||
"name": "test app",
|
||||
"website": null,
|
||||
"name": "Test Application",
|
||||
"website": "https://app.example",
|
||||
"scopes": ["read", "write", "push"],
|
||||
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
|
||||
"redirect_uris": ["urn:ietf:wg:oauth:2.0:oob"],
|
||||
"client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
|
||||
"client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw",
|
||||
"vapid_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
|
||||
"client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw"
|
||||
}
|
||||
```
|
||||
|
||||
Or with multiple redirect URIs:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "563419",
|
||||
"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"
|
||||
],
|
||||
"client_id": "TWhM-tNSuncnqN7DBJmoyeLnk6K3iJJ71KKXxgL1hPM",
|
||||
"client_secret": "ZEaFUFmF0umgBX1qKJDjaU99Q31lDkOU8NutzTOoliw"
|
||||
}
|
||||
```
|
||||
|
||||
{{< hint style="info" >}}
|
||||
The `redirect_uri` property in the above examples is considered deprecated as of 4.3.0 and should not be used, instead use the `redirect_uris` property.
|
||||
{{< /hint >}}
|
||||
|
||||
##### 422: Unprocessable entity
|
||||
|
||||
If a required parameter is missing or improperly formatted, the request will fail.
|
||||
@ -83,29 +141,37 @@ GET /api/v1/apps/verify_credentials HTTP/1.1
|
||||
|
||||
Confirm that the app's OAuth2 credentials work.
|
||||
|
||||
**Returns:** [Application]({{< relref "entities/application" >}}), but without `client_id` or `client_secret`\
|
||||
**OAuth level:** App token + `read`\
|
||||
**Returns:** [Application]({{< relref "entities/application" >}})\
|
||||
**OAuth:** App token\
|
||||
**Version history:**\
|
||||
2.0.0 - added\
|
||||
2.7.2 - now returns `vapid_key`
|
||||
2.7.2 - now returns `vapid_key`\
|
||||
4.3.0 - deprecated `vapid_key`, please see [api/v2/instance]({{< relref "methods/Instance#v2">}})\
|
||||
4.3.0 - removed needing `read` scope to access this API, now any valid App token can be used\
|
||||
4.3.0 - added `scopes` and `redirect_uris` properties
|
||||
|
||||
#### Request
|
||||
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: {{<required>}} Provide this header with `Bearer <app token>` to gain authorized access to this API method.
|
||||
: {{<required>}} Provide this header with `Bearer <app_token>` to gain authorized access to this API method. `<app_token>` may be either a `client_credential` or `access_token` returned from [`/oauth/token`]({{< relref "methods/oauth#token" >}})
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
If the Authorization header was provided with a valid token, you should see your app returned as an Application entity.
|
||||
|
||||
```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_uris": [
|
||||
"https://app.example/callback",
|
||||
"https://app.example/register"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ GET /api/v1/blocks HTTP/1.1
|
||||
##### 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
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Statuses the user has bookmarked.
|
||||
##### 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
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ GET /api/v1/conversations HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -143,7 +143,7 @@ Removes a conversation from your list of conversations.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -195,7 +195,7 @@ POST /api/v1/conversations/:id/read HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -35,7 +35,7 @@ View domains the user has blocked.
|
||||
##### 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
|
||||
|
||||
@ -100,7 +100,7 @@ Block a domain to:
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -162,7 +162,7 @@ Remove a domain block, if it exists in the user's array of blocked domains.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ Resend a new confirmation email. If an email is provided, updates the unconfirme
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Accounts that the user is currently featuring on their profile.
|
||||
##### 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
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ Statuses the user has favourited.
|
||||
##### 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
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ List all hashtags featured on your profile.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -81,7 +81,7 @@ Promote a hashtag on your profile.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -148,7 +148,7 @@ Stop promoting a hashtag on your profile.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -198,7 +198,7 @@ Shows up to 10 recently-used tags.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -38,7 +38,7 @@ Obtain a list of all filter groups for the current user.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -111,7 +111,7 @@ Obtain a single filter group owned by the current user.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -186,7 +186,7 @@ Create a filter group with the given parameters.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -310,7 +310,7 @@ Update a filter group with the given parameters.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -416,7 +416,7 @@ Delete a filter group with the given id.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -472,7 +472,7 @@ List all keywords attached to the current filter group.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -533,7 +533,7 @@ Add the given keyword to the specified filter group
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -609,7 +609,7 @@ Get one filter keyword by the given id.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -667,7 +667,7 @@ Update the given filter keyword.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -745,7 +745,7 @@ Deletes the given filter keyword.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -801,7 +801,7 @@ Obtain a list of all status filters within this filter group.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -861,7 +861,7 @@ Add a status filter to the current filter group.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -925,7 +925,7 @@ Obtain a single status filter.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -982,7 +982,7 @@ Remove a status filter from the current filter group.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1021,7 +1021,7 @@ Prior to Mastodon 4.0, matching filters was done client-size and filters could o
|
||||
|
||||
---
|
||||
|
||||
### View your filters {#get-v1}
|
||||
### View your filters {{%deprecated%}} {#get-v1}
|
||||
|
||||
```http
|
||||
GET /api/v1/filters HTTP/1.1
|
||||
@ -1037,7 +1037,7 @@ GET /api/v1/filters HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1086,7 +1086,7 @@ Invalid or missing Authorization header.
|
||||
|
||||
---
|
||||
|
||||
### View a single filter {#get-one-v1}
|
||||
### View a single filter {{%deprecated%}} {#get-one-v1}
|
||||
|
||||
```http
|
||||
GET /api/v1/filters/:id HTTP/1.1
|
||||
@ -1108,7 +1108,7 @@ GET /api/v1/filters/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1151,7 +1151,7 @@ Filter ID does not exist, or is not owned by you
|
||||
|
||||
---
|
||||
|
||||
### Create a filter {#create-v1}
|
||||
### Create a filter {{%deprecated%}} {#create-v1}
|
||||
|
||||
```http
|
||||
POST /api/v1/filters HTTP/1.1
|
||||
@ -1168,7 +1168,7 @@ POST /api/v1/filters HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1238,7 +1238,7 @@ If context is not provided properly:
|
||||
|
||||
---
|
||||
|
||||
### Update a filter {#update-v1}
|
||||
### Update a filter {{%deprecated%}} {#update-v1}
|
||||
|
||||
```http
|
||||
PUT /api/v1/filters/:id HTTP/1.1
|
||||
@ -1251,7 +1251,7 @@ Replaces a filter's parameters in-place.
|
||||
**Version history:**\
|
||||
2.4.3 - added\
|
||||
3.1.0 - added `account` context to filter in profile views\
|
||||
4.0.0 - deprecated. or compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute). This method will return an error if you attempt to change `expires_in`, `irreversible`, or `context` for a filter with multiple keywords. Changing `phrase` and `whole_word` is always safe.
|
||||
4.0.0 - deprecated. For compatibility purposes, now returns a V1::Filter representing one FilterKeyword (with the `keyword` being presented in the `phrase` attribute). This method will return an error if you attempt to change `expires_in`, `irreversible`, or `context` for a filter with multiple keywords. Changing `phrase` and `whole_word` is always safe.
|
||||
|
||||
#### Request
|
||||
|
||||
@ -1263,7 +1263,7 @@ Replaces a filter's parameters in-place.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1343,7 +1343,7 @@ If context is not provided properly:
|
||||
|
||||
---
|
||||
|
||||
### Remove a filter {#delete-v1}
|
||||
### Remove a filter {{%deprecated%}} {#delete-v1}
|
||||
|
||||
```http
|
||||
DELETE /api/v1/filters/:id HTTP/1.1
|
||||
@ -1365,7 +1365,7 @@ DELETE /api/v1/filters/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -34,7 +34,7 @@ GET /api/v1/follow_requests HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -111,7 +111,7 @@ POST /api/v1/follow_requests/:account_id/authorize HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -178,7 +178,7 @@ POST /api/v1/follow_requests/:account_id/reject HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -36,7 +36,7 @@ List your followed hashtags.
|
||||
##### 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
|
||||
|
||||
|
||||
@ -28,7 +28,8 @@ Obtain general information about the server.
|
||||
**Returns:** [Instance]({{< relref "entities/Instance" >}})\
|
||||
**OAuth:** Public\
|
||||
**Version history:**\
|
||||
4.0.0 - added
|
||||
4.0.0 - added\
|
||||
4.3.0 - added `configuration.vapid.public_key`
|
||||
|
||||
#### Response
|
||||
|
||||
@ -204,7 +205,6 @@ Obtain general information about the server.
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## List of connected domains {#peers}
|
||||
@ -226,7 +226,7 @@ Domains that this instance is aware of.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
|
||||
@ -267,9 +267,10 @@ Instance activity over the last 3 months, binned weekly.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
Each hash in the array will contain the following attributes:
|
||||
@ -377,7 +378,6 @@ If the instance is in whitelist mode and the Authorization header is missing or
|
||||
|
||||
## List of rules {#rules}
|
||||
|
||||
|
||||
```http
|
||||
GET /api/v1/instance/rules HTTP/1.1
|
||||
```
|
||||
@ -390,6 +390,7 @@ Rules that the users of this service should follow.
|
||||
3.4.0 - added
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
```json
|
||||
@ -441,9 +442,10 @@ Obtain a list of domains that have been blocked.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
The complete list of domains blocked by this instance
|
||||
@ -451,17 +453,17 @@ The complete list of domains blocked by this instance
|
||||
```json
|
||||
[
|
||||
{
|
||||
"domain":"birb.elfenban.de",
|
||||
"digest":"5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280",
|
||||
"severity":"suspend",
|
||||
"comment":"Third-party bots"
|
||||
"domain": "birb.elfenban.de",
|
||||
"digest": "5d2c6e02a0cced8fb05f32626437e3d23096480b47efbba659b6d9e80c85d280",
|
||||
"severity": "suspend",
|
||||
"comment": "Third-party bots"
|
||||
},
|
||||
{
|
||||
"domain":"birdbots.leptonics.com",
|
||||
"digest":"ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4",
|
||||
"severity":"suspend",
|
||||
"comment":"Third-party bots"
|
||||
},
|
||||
"domain": "birdbots.leptonics.com",
|
||||
"digest": "ce019d8d32cce8e369ac4367f4dc232103e6f489fbdd247fb99f9c8a646078a4",
|
||||
"severity": "suspend",
|
||||
"comment": "Third-party bots"
|
||||
}
|
||||
// ...
|
||||
]
|
||||
```
|
||||
@ -481,6 +483,7 @@ Invalid or missing Authorization header, if the admin has chosen to show domain
|
||||
The admin has chosen to show domain blocks to no one. The response body is empty; only the HTTP 404 error code is relevant.
|
||||
|
||||
```text
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
@ -499,12 +502,13 @@ Obtain an extended description of this server
|
||||
4.0.0 - added
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
```json
|
||||
{
|
||||
"updated_at":"2022-11-03T04:09:07Z",
|
||||
"content":"<p>For inquiries not related specifically to the operation of this server, such as press inquiries, please contact <a href=\"mailto:press@joinmastodon.org\">press@joinmastodon.org</a>.</p>\n\n<h2>Funding</h2>\n\n<p>This server is crowdfunded by <a href=\"https://patreon.com/mastodon\">Patreon donations</a>. For a list of sponsors, see <a href=\"https://joinmastodon.org/sponsors\">joinmastodon.org</a>.</p>\n\n<h2>Reporting and moderation</h2>\n\n<p>When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.</p>\n\n<p>We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.</p>\n\n<h2>Impressum</h2>\n\n<p>Mastodon gGmbH<br>\nMühlenstraße 8a<br>\n14167 Berlin<br>\nGermany</p>\n\n<p>E-Mail-Adresse: hello@joinmastodon.org</p>\n\n<p>Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)</p>\n\n<p>Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260</p>\n\n<p>Handelsregister<br>\nGeführt bei: Amtsgericht Charlottenburg<br>\nNummer: HRB 230086 B</p>\n"
|
||||
"updated_at": "2022-11-03T04:09:07Z",
|
||||
"content": "<p>For inquiries not related specifically to the operation of this server, such as press inquiries, please contact <a href=\"mailto:press@joinmastodon.org\">press@joinmastodon.org</a>.</p>\n\n<h2>Funding</h2>\n\n<p>This server is crowdfunded by <a href=\"https://patreon.com/mastodon\">Patreon donations</a>. For a list of sponsors, see <a href=\"https://joinmastodon.org/sponsors\">joinmastodon.org</a>.</p>\n\n<h2>Reporting and moderation</h2>\n\n<p>When reporting accounts, please make sure to include at least a few posts that show rule-breaking behaviour, when applicable. If there is any additional context that might help make a decision, please also include it in the comment. This is especially important when the content is in a language nobody on the moderation team speaks.</p>\n\n<p>We usually handle reports within 24 hours. Please mind that you are not notified when a report you have made has led to a punitive action, and that not all punitive actions are externally visible. For first time offenses, we may opt to delete offending content, escalating to harsher measures on repeat offenses.</p>\n\n<h2>Impressum</h2>\n\n<p>Mastodon gGmbH<br>\nMühlenstraße 8a<br>\n14167 Berlin<br>\nGermany</p>\n\n<p>E-Mail-Adresse: hello@joinmastodon.org</p>\n\n<p>Vertretungsberechtigt: Eugen Rochko (Geschäftsführer)</p>\n\n<p>Umsatzsteuer Identifikationsnummer (USt-ID): DE344258260</p>\n\n<p>Handelsregister<br>\nGeführt bei: Amtsgericht Charlottenburg<br>\nNummer: HRB 230086 B</p>\n"
|
||||
}
|
||||
```
|
||||
|
||||
@ -524,6 +528,7 @@ Translation language pairs supported by the translation engine used by the serve
|
||||
4.2.0 - added
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
All source and target language pairs supported by the server.
|
||||
@ -540,13 +545,13 @@ In the following sample response showing support for translating a status writte
|
||||
|
||||
---
|
||||
|
||||
## (DEPRECATED) View server information (V1) {#v1}
|
||||
## View server information (v1) {{%deprecated%}} {#v1}
|
||||
|
||||
```http
|
||||
GET /api/v1/instance HTTP/1.1
|
||||
```
|
||||
|
||||
Obtain general information about the server.
|
||||
Obtain general information about the server. See [api/v2/instance]({{< relref "methods/Instance#v2">}}) instead.
|
||||
|
||||
**Returns:** [V1::Instance]({{< relref "entities/V1_Instance" >}})\
|
||||
**OAuth:** Public\
|
||||
@ -564,35 +569,33 @@ Obtain general information about the server.
|
||||
|
||||
```json
|
||||
{
|
||||
"uri":"mastodon.social",
|
||||
"title":"Mastodon",
|
||||
"short_description":"The original server operated by the Mastodon gGmbH non-profit",
|
||||
"description":"",
|
||||
"email":"staff@mastodon.social",
|
||||
"version":"3.5.3",
|
||||
"urls":{
|
||||
"streaming_api":"wss://mastodon.social"
|
||||
"uri": "mastodon.social",
|
||||
"title": "Mastodon",
|
||||
"short_description": "The original server operated by the Mastodon gGmbH non-profit",
|
||||
"description": "",
|
||||
"email": "staff@mastodon.social",
|
||||
"version": "3.5.3",
|
||||
"urls": {
|
||||
"streaming_api": "wss://mastodon.social"
|
||||
},
|
||||
"stats":{
|
||||
"user_count":812303,
|
||||
"status_count":38151616,
|
||||
"domain_count":25255
|
||||
"stats": {
|
||||
"user_count": 812303,
|
||||
"status_count": 38151616,
|
||||
"domain_count": 25255
|
||||
},
|
||||
"thumbnail":"https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png",
|
||||
"languages":[
|
||||
"en"
|
||||
],
|
||||
"registrations":false,
|
||||
"approval_required":false,
|
||||
"invites_enabled":true,
|
||||
"configuration":{
|
||||
"statuses":{
|
||||
"max_characters":500,
|
||||
"max_media_attachments":4,
|
||||
"characters_reserved_per_url":23
|
||||
"thumbnail": "https://files.mastodon.social/site_uploads/files/000/000/001/original/vlcsnap-2018-08-27-16h43m11s127.png",
|
||||
"languages": ["en"],
|
||||
"registrations": false,
|
||||
"approval_required": false,
|
||||
"invites_enabled": true,
|
||||
"configuration": {
|
||||
"statuses": {
|
||||
"max_characters": 500,
|
||||
"max_media_attachments": 4,
|
||||
"characters_reserved_per_url": 23
|
||||
},
|
||||
"media_attachments":{
|
||||
"supported_mime_types":[
|
||||
"media_attachments": {
|
||||
"supported_mime_types": [
|
||||
"image/jpeg",
|
||||
"image/png",
|
||||
"image/gif",
|
||||
@ -619,17 +622,17 @@ Obtain general information about the server.
|
||||
"audio/3gpp",
|
||||
"video/x-ms-asf"
|
||||
],
|
||||
"image_size_limit":10485760,
|
||||
"image_matrix_limit":16777216,
|
||||
"video_size_limit":41943040,
|
||||
"video_frame_rate_limit":60,
|
||||
"video_matrix_limit":2304000
|
||||
"image_size_limit": 10485760,
|
||||
"image_matrix_limit": 16777216,
|
||||
"video_size_limit": 41943040,
|
||||
"video_frame_rate_limit": 60,
|
||||
"video_matrix_limit": 2304000
|
||||
},
|
||||
"polls":{
|
||||
"max_options":4,
|
||||
"max_characters_per_option":50,
|
||||
"min_expiration":300,
|
||||
"max_expiration":2629746
|
||||
"polls": {
|
||||
"max_options": 4,
|
||||
"max_characters_per_option": 50,
|
||||
"min_expiration": 300,
|
||||
"max_expiration": 2629746
|
||||
}
|
||||
},
|
||||
"contact_account":{
|
||||
@ -657,36 +660,36 @@ Obtain general information about the server.
|
||||
],
|
||||
"fields":[
|
||||
{
|
||||
"name":"Patreon",
|
||||
"value":"\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e",
|
||||
"verified_at":null
|
||||
"name": "Patreon",
|
||||
"value": "\u003ca href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"\u003e\u003cspan class=\"invisible\"\u003ehttps://www.\u003c/span\u003e\u003cspan class=\"\"\u003epatreon.com/mastodon\u003c/span\u003e\u003cspan class=\"invisible\"\u003e\u003c/span\u003e\u003c/a\u003e",
|
||||
"verified_at": null
|
||||
}
|
||||
]
|
||||
},
|
||||
"rules":[
|
||||
"rules": [
|
||||
{
|
||||
"id":"1",
|
||||
"text":"Sexually explicit or violent media must be marked as sensitive when posting"
|
||||
"id": "1",
|
||||
"text": "Sexually explicit or violent media must be marked as sensitive when posting"
|
||||
},
|
||||
{
|
||||
"id":"2",
|
||||
"text":"No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
|
||||
"id": "2",
|
||||
"text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
|
||||
},
|
||||
{
|
||||
"id":"3",
|
||||
"text":"No incitement of violence or promotion of violent ideologies"
|
||||
"id": "3",
|
||||
"text": "No incitement of violence or promotion of violent ideologies"
|
||||
},
|
||||
{
|
||||
"id":"4",
|
||||
"text":"No harassment, dogpiling or doxxing of other users"
|
||||
"id": "4",
|
||||
"text": "No harassment, dogpiling or doxxing of other users"
|
||||
},
|
||||
{
|
||||
"id":"5",
|
||||
"text":"No content illegal in Germany"
|
||||
"id": "5",
|
||||
"text": "No content illegal in Germany"
|
||||
},
|
||||
{
|
||||
"id":"7",
|
||||
"text":"Do not share intentionally false or misleading information"
|
||||
"id": "7",
|
||||
"text": "Do not share intentionally false or misleading information"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@ -38,7 +38,7 @@ Fetch all lists that the user owns.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -97,7 +97,7 @@ Fetch the list with the given ID. Used for verifying the title of a list, and wh
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -154,7 +154,7 @@ Create a new list.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -236,7 +236,7 @@ Change the title of a list, or which replies to show.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -314,7 +314,7 @@ DELETE /api/v1/lists/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -370,7 +370,7 @@ GET /api/v1/lists/:id/accounts HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -476,7 +476,7 @@ Add accounts to the given list. Note that the user must be following these accou
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -545,7 +545,7 @@ Remove accounts from the given list.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Get current positions in timelines.
|
||||
##### 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
|
||||
|
||||
@ -93,7 +93,7 @@ Save current position in timeline.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -39,7 +39,7 @@ Creates a media attachment to be used with a new status. The full sized media wi
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -182,7 +182,7 @@ Get a media attachment, before it is attached to a status and posted, but after
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -286,7 +286,7 @@ Update a MediaAttachment's parameters, before it is attached to a status and pos
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -366,7 +366,7 @@ Attachment is not owned by you or does not exist
|
||||
|
||||
---
|
||||
|
||||
## (DEPRECATED) Upload media as an attachment {#v1}
|
||||
## Upload media as an attachment (v1) {{%deprecated%}} {#v1}
|
||||
|
||||
```http
|
||||
POST /api/v1/media HTTP/1.1
|
||||
@ -386,7 +386,7 @@ Creates an attachment to be used with a new status. This method will return afte
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Accounts the user has muted.
|
||||
##### 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
|
||||
|
||||
|
||||
@ -55,7 +55,7 @@ Types to filter include:
|
||||
##### 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
|
||||
|
||||
@ -89,7 +89,7 @@ Sample call with limit=2.
|
||||
|
||||
```http
|
||||
GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1
|
||||
Authorization: Bearer xxx
|
||||
Authorization: Bearer <user_token>
|
||||
```
|
||||
|
||||
##### 200: OK
|
||||
@ -200,7 +200,7 @@ View information about a notification with a given ID.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
|
||||
@ -276,7 +276,7 @@ Clear all notifications from the server.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
|
||||
@ -323,7 +323,7 @@ Dismiss a single notification from the server.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
|
||||
@ -347,7 +347,7 @@ Invalid or missing Authorization header.
|
||||
|
||||
---
|
||||
|
||||
## (REMOVED) Dismiss a single notification {#dismiss-deprecated}
|
||||
## Dismiss a single notification {{%removed%}} {#dismiss-deprecated}
|
||||
|
||||
```http
|
||||
POST /api/v1/notifications/dismiss HTTP/1.1
|
||||
@ -367,7 +367,7 @@ Dismiss a single notification from the server.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
id
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
title: oauth API methods
|
||||
title: OAuth API methods
|
||||
description: Generate and manage OAuth tokens.
|
||||
menu:
|
||||
docs:
|
||||
@ -7,11 +7,7 @@ menu:
|
||||
name: oauth
|
||||
parent: methods-apps
|
||||
identifier: methods-oauth
|
||||
aliases: [
|
||||
"/methods/oauth",
|
||||
"/api/methods/oauth",
|
||||
"/methods/apps/oauth",
|
||||
]
|
||||
aliases: ["/methods/oauth", "/api/methods/oauth", "/methods/apps/oauth"]
|
||||
---
|
||||
|
||||
<style>
|
||||
@ -32,8 +28,10 @@ Displays an authorization form to the user. If approved, it will create and retu
|
||||
0.1.0 - added\
|
||||
2.6.0 - added `force_login`\
|
||||
3.5.0 - added `lang`
|
||||
4.3.0 - added support for PKCE parameters
|
||||
|
||||
#### Request
|
||||
|
||||
##### Query parameters
|
||||
|
||||
response_type
|
||||
@ -45,8 +43,17 @@ client_id
|
||||
redirect_uri
|
||||
: {{<required>}} String. Set a URI to redirect the user to. If this parameter is set to `urn:ietf:wg:oauth:2.0:oob` then the authorization code will be shown instead. Must match one of the `redirect_uris` declared during app registration.
|
||||
|
||||
scope
|
||||
: String. List of requested OAuth scopes, separated by spaces (or by pluses, if using query parameters). Must be a subset of `scopes` declared during app registration. If not provided, defaults to `read`.
|
||||
scope<
|
||||
: String. List of requested [OAuth scopes]({{< relref "api/oauth-scopes" >}}), separated by spaces (or by pluses, if using query parameters). Must be a subset of `scopes` declared during app registration. If not provided, defaults to `read`.
|
||||
|
||||
state
|
||||
: String. Arbitrary value to passthrough to your server when the user authorizes or rejects the authorization request.
|
||||
|
||||
code_challenge
|
||||
: String. The [PKCE code challenge]({{< relref "spec/oauth#pkce" >}}) for the authorization request.
|
||||
|
||||
code_challenge_method
|
||||
: String. Must be `S256`, as this is the only code challenge method that is supported by Mastodon for PKCE.
|
||||
|
||||
force_login
|
||||
: Boolean. Forces the user to re-login, which is necessary for authorizing with multiple accounts from the same instance.
|
||||
@ -55,14 +62,25 @@ lang
|
||||
: String. The ISO 639-1 two-letter language code to use while rendering the authorization form.
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
The authorization code will be returned as a query parameter named `code`.
|
||||
|
||||
{{< 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 >}}
|
||||
|
||||
```http
|
||||
redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU
|
||||
```
|
||||
|
||||
If the state parameter was used, then this will also be present in the URI when the client is redirected.
|
||||
|
||||
```http
|
||||
redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU&state=example
|
||||
```
|
||||
|
||||
##### 400: Client error
|
||||
|
||||
If the authorization code is incorrect or has been used already, the request will fail.
|
||||
@ -88,15 +106,17 @@ Obtain an access token, to be used during API calls that are not public.
|
||||
**OAuth:** Public\
|
||||
**Version history:**\
|
||||
0.1.0 - added
|
||||
4.3.0 - added support for PKCE parameter
|
||||
|
||||
#### Request
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
grant_type
|
||||
: {{<required>}} String. Set equal to `authorization_code` if `code` is provided in order to gain user-level access. Otherwise, set equal to `client_credentials` to obtain app-level access only.
|
||||
|
||||
code
|
||||
: String. A user authorization code, obtained via [GET /oauth/authorize](#authorize).
|
||||
: {{<required>}} String. A user authorization code, obtained from the redirect after an [Authorization request](#authorize) is approved. May alternatively be displayed to the user if `urn:ietf:wg:oauth:2.0:oob` is used as the `redirect_uri`.
|
||||
|
||||
client_id
|
||||
: {{<required>}} String. The client ID, obtained during app registration.
|
||||
@ -105,15 +125,25 @@ client_secret
|
||||
: {{<required>}} String. The client secret, obtained during app registration.
|
||||
|
||||
redirect_uri
|
||||
: {{<required>}} String. Set a URI to redirect the user to. If this parameter is set to urn:ietf:wg:oauth:2.0:oob then the token will be shown instead. Must match one of the `redirect_uris` declared during app registration.
|
||||
: {{<required>}} String. Must match the `redirect_uri` used during the [Authorization request](#authorize).
|
||||
|
||||
code_verifier
|
||||
: String. Required if [PKCE]({{< relref "spec/oauth#pkce" >}}) is used during the authorization request. This is the code verifier which was used to create the `code_challenge` using the `code_challenge_method` for the authorization request.
|
||||
|
||||
scope
|
||||
: String. When `grant_type` is set to `client_credentials`, the list of requested OAuth scopes, separated by spaces (or pluses, if using query parameters). Must be a subset of the scopes requested at the time the application was created. If omitted, it defaults to `read`. Has no effect when `grant_type` is `authorization_code`.
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
Store this access_token for later use with auth-required methods. The token should be passed as an HTTP `Authorization` header when making API calls, with the value `Bearer access_token`
|
||||
Store this `access_token` for later use with methods that require authentication. The token should be passed as an HTTP `Authorization` header when making API calls, with the value `Bearer <access_token>`
|
||||
|
||||
{{< 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 credential exposure.\
|
||||
\
|
||||
Additionally, you should ensure that the `code` parameter is not logged.
|
||||
{{< /hint >}}
|
||||
|
||||
```json
|
||||
{
|
||||
@ -159,9 +189,10 @@ Revoke an access token to make it no longer valid for use.
|
||||
**Returns:** Empty\
|
||||
**OAuth:** Public\
|
||||
**Version history:**\
|
||||
x.x.x - added
|
||||
0.1.0 - added
|
||||
|
||||
#### Request
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
client_id
|
||||
@ -174,6 +205,7 @@ token
|
||||
: {{<required>}} String. The previously obtained token, to be invalidated.
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
If you own the provided token, the API call will provide an empty response. This operation is idempotent, so calling this API multiple times will still return OK.
|
||||
@ -195,6 +227,112 @@ If you provide a token you do not own, or no token at all, the API call will ret
|
||||
|
||||
---
|
||||
|
||||
## Discover OAuth Server Configuration {#authorization-server-metadata}
|
||||
|
||||
```http
|
||||
GET /.well-known/oauth-authorization-server HTTP/1.1
|
||||
```
|
||||
|
||||
Returns the OAuth 2 Authorization Server Metadata for the Mastodon server, as defined by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3.2).
|
||||
|
||||
We include the additional non-standard property of `app_registration_endpoint` which refers to the [POST /api/v1/apps]({{% relref ref="methods/apps#create" %}}) endpoint, since we don't currently support the standard `registration_endpoint` endpoint for [Dynamic Client Registration](https://oauth.net/2/dynamic-client-registration/).
|
||||
|
||||
The properties exposed by this endpoint can help you better integrate with the Mastodon API, such as allowing for negotiation of `scopes` across different versions of Mastodon.
|
||||
|
||||
{{< 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 to this endpoint.
|
||||
{{< /hint >}}
|
||||
|
||||
**Returns:** JSON as per the above description\
|
||||
**OAuth:** Public\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
#### Response
|
||||
|
||||
##### 200: OK
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://social.example/",
|
||||
"service_documentation": "https://docs.joinmastodon.org/",
|
||||
"authorization_endpoint": "https://social.example/oauth/authorize",
|
||||
"token_endpoint": "https://social.example/oauth/token",
|
||||
"app_registration_endpoint": "https://social.example/api/v1/apps",
|
||||
"revocation_endpoint": "https://social.example/oauth/revoke",
|
||||
"scopes_supported": [
|
||||
"read",
|
||||
"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",
|
||||
"read:accounts",
|
||||
"read:blocks",
|
||||
"read:bookmarks",
|
||||
"read:favourites",
|
||||
"read:filters",
|
||||
"read:follows",
|
||||
"read:lists",
|
||||
"read:mutes",
|
||||
"read:notifications",
|
||||
"read:search",
|
||||
"read:statuses",
|
||||
"follow",
|
||||
"push",
|
||||
"profile",
|
||||
"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"
|
||||
],
|
||||
"response_types_supported": ["code"],
|
||||
"response_modes_supported": ["query", "fragment", "form_post"],
|
||||
"code_challenge_methods_supported": [
|
||||
"S256"
|
||||
],
|
||||
"grant_types_supported": [
|
||||
"authorization_code",
|
||||
"client_credentials"
|
||||
],
|
||||
"token_endpoint_auth_methods_supported": [
|
||||
"client_secret_basic",
|
||||
"client_secret_post"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Older Mastodon Versions – 404: Not Found
|
||||
|
||||
On Mastodon versions before 4.3.0, requesting this endpoint will result in a `404 Not Found` error.
|
||||
|
||||
Instead, you will need to "guess" what that server supports, instead of discovering supported OAuth 2 endpoints, grant flows & scopes dynamically.
|
||||
|
||||
You may want to fallback to the [Instance Metadata endpoint]({{% relref ref="methods/instance#v2" %}}) to try to discover what Mastodon version the server is running by parsing the `version` field; however, this is very brittle and not recommended.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}}
|
||||
|
||||
@ -43,7 +43,7 @@ View a poll attached to a status.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -109,7 +109,7 @@ Vote on a poll attached to a status.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -36,7 +36,7 @@ Preferences defined by the user in their account settings.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -20,7 +20,7 @@ DELETE /api/v1/profile/avatar HTTP/1.1
|
||||
```
|
||||
|
||||
**Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
|
||||
**OAuth**: User token + `write:accounts`\
|
||||
**OAuth:** User token + `write:accounts`\
|
||||
**Version history:**\
|
||||
4.2.0 - added
|
||||
|
||||
@ -31,7 +31,7 @@ Deletes the avatar associated with the user's profile.
|
||||
##### 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.
|
||||
|
||||
##### Path parameters
|
||||
|
||||
@ -102,7 +102,7 @@ DELETE /api/v1/profile/header HTTP/1.1
|
||||
```
|
||||
|
||||
**Returns:** [CredentialAccount]({{< relref "entities/Account#CredentialAccount">}})\
|
||||
**OAuth**: User token + `write:accounts`\
|
||||
**OAuth:** User token + `write:accounts`\
|
||||
**Version history:**\
|
||||
4.2.0 - added
|
||||
|
||||
@ -113,7 +113,7 @@ Deletes the header image associated with the user's profile.
|
||||
##### 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.
|
||||
|
||||
##### Path parameters
|
||||
|
||||
|
||||
@ -23,7 +23,7 @@ aliases: [
|
||||
Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only proof provider was Keybase, but development on Keybase has stalled entirely since it was acquired by Zoom.
|
||||
{{< /hint >}}
|
||||
|
||||
## (REMOVED) View identity proofs {#get}
|
||||
## View identity proofs {{%removed%}} {#get}
|
||||
|
||||
```http
|
||||
GET /api/proofs HTTP/1.1
|
||||
|
||||
@ -45,14 +45,15 @@ Add a Web Push API subscription to receive notifications. Each access token can
|
||||
3.3.0 - added `data[alerts][status]`\
|
||||
3.4.0 - added `data[policy]`\
|
||||
3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]`\
|
||||
4.0.0 - added `data[alerts][admin.report]`
|
||||
4.0.0 - added `data[alerts][admin.report]`\
|
||||
4.3.0 - added stricter request parameter validation, invalid endpoint URLs and subscription keys will now result in an error, previously these would be accepted, but silently fail.
|
||||
|
||||
#### Request
|
||||
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -147,7 +148,7 @@ View the PushSubscription currently associated with this access token.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -211,7 +212,7 @@ Updates the current push subscription. Only the data part can be updated. To cha
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -308,7 +309,7 @@ Removes the current Web Push API subscription.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ POST /api/v1/reports HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
|
||||
@ -35,7 +35,7 @@ GET /api/v1/scheduled_statuses HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -109,7 +109,7 @@ GET /api/v1/scheduled_statuses/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -177,7 +177,7 @@ PUT /api/v1/scheduled_statuses/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -258,7 +258,7 @@ DELETE /api/v1/scheduled_statuses/:id HTTP/1.1
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -37,7 +37,7 @@ GET /api/v2/search HTTP/1.1
|
||||
##### 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
|
||||
|
||||
@ -152,7 +152,7 @@ Invalid or missing Authorization header.
|
||||
|
||||
---
|
||||
|
||||
## (REMOVED) Search results (v1) {#v1}
|
||||
## Perform a search (v1) {{%removed%}} {#v1}
|
||||
|
||||
```http
|
||||
GET /api/v1/search HTTP/1.1
|
||||
@ -172,7 +172,7 @@ GET /api/v1/search HTTP/1.1
|
||||
##### 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
|
||||
|
||||
|
||||
@ -38,7 +38,7 @@ Publish a status with the given parameters.
|
||||
##### 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.
|
||||
|
||||
Idempotency-Key
|
||||
: Provide this header with any arbitrary string to prevent duplicate submissions of the same status. Consider using a hash or UUID generated client-side. Idempotency keys are stored for up to 1 hour.
|
||||
@ -167,7 +167,7 @@ Obtain information about a status.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -280,7 +280,7 @@ id[]
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -389,7 +389,7 @@ Delete one of your own statuses.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -579,7 +579,7 @@ View statuses above and below this status in the thread.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -661,7 +661,7 @@ lang
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -754,7 +754,7 @@ View who boosted a given status.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -825,7 +825,7 @@ View who favourited a given status.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -896,7 +896,7 @@ Add a status to your favourites list.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -962,7 +962,7 @@ Remove a status from your favourites list.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1029,7 +1029,7 @@ Reshare a status on your own profile.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1111,7 +1111,7 @@ Undo a reshare of a status.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1177,7 +1177,7 @@ Privately bookmark a status.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1233,7 +1233,7 @@ Remove a status from your private bookmarks.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1299,7 +1299,7 @@ Do not receive notifications for the thread that this status is part of. Must be
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1365,7 +1365,7 @@ Start receiving notifications again for the thread that this status is part of.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1432,7 +1432,7 @@ Feature one of your own public statuses at the top of your profile.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1525,7 +1525,7 @@ Unfeature a status from the top of your profile.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1601,7 +1601,7 @@ Edit a given status to change its text, sensitivity, media attachments, or poll.
|
||||
##### 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.
|
||||
|
||||
##### Form data parameters
|
||||
|
||||
@ -1737,7 +1737,7 @@ Get all known versions of a status, including the initial and current states.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1883,7 +1883,7 @@ Obtain the source properties for a status so that it can be edited.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -1918,7 +1918,7 @@ Status does not exist or is private.
|
||||
|
||||
---
|
||||
|
||||
## (DEPRECATED) Fetch preview card {#card}
|
||||
## Fetch preview card {{%deprecated%}} {#card}
|
||||
|
||||
```http
|
||||
GET /api/v1/statuses/:id/card HTTP/1.1
|
||||
@ -1941,7 +1941,7 @@ GET /api/v1/statuses/:id/card HTTP/1.1
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -160,7 +160,7 @@ Returns events that are relevant to the authorized user, i.e. home timeline and
|
||||
##### 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.
|
||||
|
||||
#### Events
|
||||
|
||||
@ -232,7 +232,7 @@ Returns events for received notifications
|
||||
##### 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.
|
||||
|
||||
#### Events
|
||||
|
||||
@ -254,17 +254,18 @@ GET /api/v1/streaming/public HTTP/1.1
|
||||
Returns all public statuses
|
||||
|
||||
**Returns:** `update`, `delete`, `status.update`\
|
||||
**OAuth:** Public, or app token + `read:statuses`\
|
||||
**OAuth:** User token + `read:statuses`\
|
||||
**Version history:**\
|
||||
1.0.0 - added\
|
||||
2.4.0 - add `only_media` parameter\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -305,17 +306,18 @@ GET /api/v1/streaming/public/local HTTP/1.1
|
||||
Returns all local public statuses
|
||||
|
||||
**Returns:** `update`, `delete`, `status.update`\
|
||||
**OAuth:** Public, or app token + `read:statuses`\
|
||||
**OAuth:** User token + `read:statuses`\
|
||||
**Version history:**\
|
||||
1.1.0 - added\
|
||||
2.4.0 - add `only_media` parameter\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -356,16 +358,17 @@ GET /api/v1/streaming/public/remote HTTP/1.1
|
||||
Returns all public statuses from remote servers.
|
||||
|
||||
**Returns:** `update`, `delete`, `status.update`\
|
||||
**OAuth:** Public, or app token + `read:statuses`\
|
||||
**OAuth:** User token + `read:statuses`\
|
||||
**Version history:**\
|
||||
3.1.4 - added\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -406,16 +409,17 @@ GET /api/v1/streaming/hashtag HTTP/1.1
|
||||
Returns all public statuses for a particular hashtag
|
||||
|
||||
**Returns:** `update`, `delete`, `status.update`\
|
||||
**OAuth:** Public, or app token + `read:statuses`\
|
||||
**OAuth:** User token + `read:statuses`\
|
||||
**Version history:**\
|
||||
1.0.0 - added\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -456,16 +460,17 @@ GET /api/v1/streaming/hashtag/local HTTP/1.1
|
||||
Returns all local public statuses for a particular hashtag
|
||||
|
||||
**Returns:** `update`, `delete`, `status.update`\
|
||||
**OAuth:** Public, or app token + `read:statuses`\
|
||||
**OAuth:** User token + `read:statuses`\
|
||||
**Version history:**\
|
||||
1.1.0 - added\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -510,12 +515,13 @@ Returns statuses for a list
|
||||
**Version history:**\
|
||||
2.1.0 - added\
|
||||
3.5.0 - now returns `status.update`
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
#### Request
|
||||
##### 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
|
||||
|
||||
@ -565,7 +571,7 @@ Returns events for received direct messages.
|
||||
##### 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.
|
||||
|
||||
#### Events
|
||||
|
||||
@ -587,9 +593,10 @@ wss://mastodon.example/api/v1/streaming
|
||||
```
|
||||
|
||||
**Returns:** Stream of [Event](#events)\
|
||||
**OAuth:** Public, or user token + `read` (or `read:statuses` and/or `read:notifications`)\
|
||||
**OAuth:** User token + `read` (or `read:statuses` and/or `read:notifications`)\
|
||||
**Version history:**\
|
||||
3.3.0 - added
|
||||
4.2.0 - changed to require a User token, removing Public and App token access [#23989](https://github.com/mastodon/mastodon/pull/23989)
|
||||
|
||||
Open a multiplexed WebSocket connection to receive events.
|
||||
|
||||
@ -644,7 +651,7 @@ An example update to the public timeline:
|
||||
```
|
||||
|
||||
{{< hint style="warning" >}}
|
||||
Note that while the event is JSON-encoded, the `payload` is string-encoded and escaped, so it must be parsed and loaded as JSON from that string.
|
||||
Note that while the event is JSON-encoded, the `payload` is string-encoded and escaped, so it must be parsed and loaded as JSON from that string. However, for `delete` and `announcements.delete` events the payload is a string representing an identifier, not a JSON value.
|
||||
{{</hint>}}
|
||||
|
||||
An example delete event from the public timeline:
|
||||
@ -671,7 +678,7 @@ An example filter change by the user:
|
||||
```
|
||||
|
||||
{{< hint style="warning" >}}
|
||||
Note that the `payload` property is not present for `filters_changed` events.
|
||||
Note that the `payload` property is not present for `filters_changed` events. And for `delete` and `announcements.delete` the payload is a string, not an object.
|
||||
{{</hint>}}
|
||||
|
||||
## See also
|
||||
|
||||
@ -37,7 +37,7 @@ Accounts that are promoted by staff, or that the user has had past positive inte
|
||||
##### 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
|
||||
|
||||
@ -104,7 +104,7 @@ Remove an account from follow suggestions.
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -127,7 +127,7 @@ Invalid or missing Authorization header.
|
||||
|
||||
---
|
||||
|
||||
## (DEPRECATED) View follow suggestions (v1) {#v1}
|
||||
## View follow suggestions (v1) {{%deprecated%}} {#v1}
|
||||
|
||||
```http
|
||||
GET /api/v1/suggestions HTTP/1.1
|
||||
@ -145,7 +145,7 @@ Accounts the user has had past positive interactions with, but is not yet follow
|
||||
##### 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
|
||||
|
||||
|
||||
@ -40,7 +40,7 @@ Show a hashtag and its associated information
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -116,7 +116,7 @@ Follow a hashtag. Posts containing a followed hashtag will be inserted into your
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
@ -213,7 +213,7 @@ Unfollow a hashtag. Posts containing this hashtag will no longer be inserted int
|
||||
##### 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.
|
||||
|
||||
#### Response
|
||||
##### 200: OK
|
||||
|
||||
@ -40,7 +40,7 @@ View public statuses.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -119,7 +119,7 @@ View public statuses containing the given hashtag.
|
||||
##### Headers
|
||||
|
||||
Authorization
|
||||
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
||||
: Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
||||
|
||||
##### Query parameters
|
||||
|
||||
@ -248,7 +248,7 @@ View statuses from followed users and hashtags.
|
||||
##### 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
|
||||
|
||||
@ -376,7 +376,7 @@ View statuses in the given list timeline.
|
||||
##### 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
|
||||
|
||||
@ -430,7 +430,7 @@ List is not owned by you or does not exist
|
||||
|
||||
---
|
||||
|
||||
## (DEPRECATED) View direct timeline {#direct}
|
||||
## View direct timeline {{%deprecated%}} {#direct}
|
||||
|
||||
```http
|
||||
GET /api/v1/timelines/direct HTTP/1.1
|
||||
@ -449,7 +449,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
|
||||
|
||||
|
||||
@ -611,7 +611,7 @@ As noted above while listing the [schema.org @context extensions](#schema), Mast
|
||||
}
|
||||
```
|
||||
|
||||
### Identity proofs {#IdentityProof}
|
||||
### Identity proofs {{%deprecated%}} {#IdentityProof}
|
||||
|
||||
{{< hint style="warning" >}}
|
||||
This property is currently unused/deprecated due to the removal of Keybase support in Mastodon 3.5: <https://github.com/mastodon/mastodon/pull/17045>
|
||||
|
||||
@ -13,41 +13,76 @@ The Mastodon API has many methods that require authentication from a client or a
|
||||
|
||||
To obtain an OAuth token for a Mastodon website, make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to [acquire a client id/secret]({{< relref "methods/apps#create" >}}) and then [proceed with normal OAuth 2]({{< relref "methods/oauth" >}}).
|
||||
|
||||
## OAuth 2 client types {#client-types}
|
||||
|
||||
OAuth 2 defines two client types: `confidential` and `public`, based on their ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials). Confidential clients are allowed to use the [client credentials grant flow]({{<relref "client/token#flow" >}}), where as public clients cannot.
|
||||
|
||||
At present Mastodon only supports confidential clients, however [work is underway](https://github.com/mastodon/mastodon/pull/30329) to add support for public clients.
|
||||
|
||||
## OAuth 2 endpoints implemented {#implementation}
|
||||
|
||||
The following descriptions are taken from the [Doorkeeper documentation](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples). Mastodon uses Doorkeeper to implement OAuth 2. For more information on how to use these endpoints, see the [API documentation for OAuth.]({{< relref "methods/oauth" >}})
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/config/initializers/doorkeeper.rb" caption="Doorkeeper config initializer" >}}
|
||||
|
||||
### Authorization endpoint (RFC 6749 Section 3.1) {#authorization}
|
||||
### Authorization Server Metadata endpoint ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html)) {#authorization-server-metadata}
|
||||
|
||||
[GET /oauth/authorize]({{% relref "methods/oauth#authorize" %}})
|
||||
Returns a JSON document representing the configuration of the OAuth 2 server in Mastodon. Information includes `scopes` available for use when [registering Applications]({{% relref "methods/apps#create" %}}) or requesting [access tokens]({{% relref "methods/oauth#token" %}}), `grant_types_supported` which are can be used when requesting access tokens, and various endpoints for interacting with the Mastodon OAuth server, such as `authorization_endpoint` and `token_endpoint`.
|
||||
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
{{< page-relref ref="methods/oauth#authorization-server-metadata" caption="GET /.well-known/oauth-authorization-server" >}}
|
||||
|
||||
### Dynamic Client Registration endpoint ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591.html)) {#dynamic-client-registration}
|
||||
|
||||
At present, Mastodon does not support the Dynamic Client Registration protocol, however it does support a proprietary endpoint for registering an OAuth Application.
|
||||
|
||||
{{< page-relref ref="methods/apps#create" caption="POST /api/v1/apps" >}}
|
||||
|
||||
### Authorization endpoint ([RFC 6749 Section 3.1](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.1)) {#authorization}
|
||||
|
||||
Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired `redirect_uri`, or show the authorization code if `urn:ietf:wg:oauth:2.0:oob` was requested.
|
||||
|
||||
### Token endpoint (RFC 6749 Section 3.2) {#token}
|
||||
{{< page-relref ref="methods/oauth#authorize" caption="GET /oauth/authorize" >}}
|
||||
|
||||
[POST /oauth/token]({{% relref "methods/oauth#token" %}})
|
||||
### Token endpoint ([RFC 6749 Section 3.2](https://www.rfc-editor.org/rfc/rfc6749.html#section-3.2)) {#token}
|
||||
|
||||
Obtain an access token. Mastodon supports the following OAuth 2 flows:
|
||||
|
||||
Authorization code flow
|
||||
: For end-users
|
||||
|
||||
Password grant flow
|
||||
: For bots and other single-user applications
|
||||
|
||||
Client credentials flow
|
||||
: For applications that do not act on behalf of users
|
||||
|
||||
### Token revocation endpoint (RFC 7009 Section 2) {#revoke}
|
||||
Mastodon has historically supported the Password Grant flow, however, usage is [not recommended](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#name-resource-owner-password-cre) by the OAuth 2 Specification authors due to security issues, and has subsequently been removed from future versions of Mastodon. Instead, it is recommended that you create an OAuth Application for that user, and use the generated Access Token for interacting with the API.
|
||||
|
||||
[POST /oauth/revoke]({{% relref "methods/oauth#revoke" %}})
|
||||
{{< page-relref ref="methods/oauth#token" caption="POST /oauth/token" >}}
|
||||
|
||||
### Token revocation endpoint ([RFC 7009 Section 2](https://www.rfc-editor.org/rfc/rfc7009.html#section-2)) {#revoke}
|
||||
|
||||
Post here with client credentials to revoke an access token.
|
||||
|
||||
{{< page-relref ref="methods/oauth#revoke" caption="POST /oauth/revoke" >}}
|
||||
|
||||
## OAuth 2 Security Considerations
|
||||
|
||||
### Proof Key for Code Exchange (PKCE) {#pkce}
|
||||
|
||||
When performing an OAuth 2 [authorization code flow]({{< relref ref="methods/oauth#authorize" >}}), there is an additional security mechanism that you can employ to increase the security of the authorization code when the user is redirected back to your application. This is known as Proof Key for Code Exchange, or PKCE (pronounced pixie), and is supported by Mastodon 4.3.0 and above.
|
||||
|
||||
We recommend, inline with [OAuth 2 Security Best Current Practices](https://www.ietf.org/archive/id/draft-ietf-oauth-security-topics-27.html#name-pkce), to use PKCE with the Authorization Code flow for both confidential clients and public clients.
|
||||
|
||||
{{< caption-link url="https://oauth.net/2/pkce/" caption="Learn more about PKCE on the OAuth.net website" >}}
|
||||
|
||||
### State Parameter {#state-parameter}
|
||||
|
||||
When performing an OAuth 2 [authorization code flow]({{< relref ref="methods/oauth#authorize" >}}), you can use the [`state` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) of the Authorization endpoint to prevent mix-up and cross site request forgery attacks. This parameter is returned back to your server unchanged via the redirect URI upon completion of the OAuth Authorization Code flow.
|
||||
|
||||
It is also possible to use this parameter to passthrough arbitrary information to your server via the Authorization Code flow. If you use the `state` parameter, it is recommended that you compare or validate the state value before finishing the authorization code flow (i.e., exchanging the authorization code for an access token).
|
||||
|
||||
## Common gotchas {#gotchas}
|
||||
|
||||
* When registering an application using Mastodon's REST API, there is a `scopes` parameter. When interfacing with OAuth endpoints, you must use the `scope` parameter instead, and this parameter's value must be a subset of the `scopes` registered with the app. You cannot include anything that wasn't in the original set.
|
||||
* When registering an application using Mastodon's REST API, there is a `redirect_uris` parameter. When interfacing with OAuth endpoints, you must use the `redirect_uri` parameter instead, and this parameter's value must be one of the `redirect_uris` registered with the app.
|
||||
|
||||
- When registering an application using Mastodon's REST API, there is a `scopes` parameter. When interfacing with OAuth endpoints, you must use the `scope` parameter instead, and this parameter's value must be a subset of the `scopes` registered with the app. You cannot include anything that wasn't in the original set.
|
||||
- When registering an application using Mastodon's REST API, there is a `redirect_uris` parameter. When interfacing with OAuth endpoints, you must use the `redirect_uri` parameter instead, and this parameter's value must be one of the `redirect_uris` registered with the app.
|
||||
|
||||
@ -46,6 +46,12 @@ other = "required"
|
||||
[optional]
|
||||
other = "optional"
|
||||
|
||||
[deprecated]
|
||||
other = "deprecated"
|
||||
|
||||
[removed]
|
||||
other = "removed"
|
||||
|
||||
[nullable]
|
||||
other = "nullable"
|
||||
|
||||
|
||||
1
layouts/shortcodes/deprecated.html
Normal file
1
layouts/shortcodes/deprecated.html
Normal file
@ -0,0 +1 @@
|
||||
<span class="api-method-parameter-deprecated">{{ i18n "deprecated" }}</span>
|
||||
1
layouts/shortcodes/removed.html
Normal file
1
layouts/shortcodes/removed.html
Normal file
@ -0,0 +1 @@
|
||||
<span class="api-method-parameter-removed">{{ i18n "removed" }}</span>
|
||||
Loading…
x
Reference in New Issue
Block a user