ffbe66a389
* fix relrefs around trends and related entities * revert moving caption-links to middle of page * hide empty menu in table of contents * clarify edit notifs are only for boosted statuses * following/followers no longer need auth * fix typo * specify cooldown period for account Move * use the correct cooldown * add missing parameters to accounts/id/statuses * link to account_statuses_filter.rb * fix typo (#1072) * fix typo (#1073) * fix link to http sig spec (#1067) * simply HTTP request examples in api methods docs * add missing client_secret to oauth/token (#1062) * Add any, all, none to hashtag timeline * minor formatting changes * Update signature requirements and advice * fix public key -> private key * clarify use of RSA with SHA256 * Add note about saving your profile after adding rel-me link * v2 filters api * comment out params that shouldn't be used in v2 filter api * admin trends * remove old todo * canonical email blocks + scheduled statuses * remove under-construction warnings from finished pages * verify api method params with source code * fix typo (#1088) * fix broken caption-links (#1100) * fix formatting of entities (#1094) * Remove keybase section from user guide (#1093) * fix typos (#1092) * Verify limits are accurate (#1086) * add mention of iframe limitation (#1084) * Add CORS header to WEB_DOMAIN example (#1083) * Fix typo (#1081) * pin http sigs spec at draft 8 * Revert "pin http sigs spec at draft 8" This reverts commit 9fd5f7032b69b29e77599dd62adfe8d2f5cd4f20. * add case sensitivity warning to 4.0 roles * Add url length note to bio (#1087) * remove follow scope from examples (#1103) * clarify usage of update_credentials to update profile fields * add noindex to Account entitity * remove required hint from technically not required property
4.8 KiB
| title | description | menu | ||||||
|---|---|---|---|---|---|---|---|---|
| OAuth Scopes | Defining what you have permission to do with the API |
|
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).
{{< hint style="info" >}}
Mind the scope vs scopes difference. This is because scope is a standard OAuth parameter name, so it is used in the OAuth methods. Mastodon’s own REST API uses the more appropriate scopes.
{{< /hint >}}
If you do not specify a scope in your authorization request, or a scopes in your app creation request, the resulting access token / app will default to read access.
The set of scopes saved during app creation must include all the scopes that you will request in the authorization request, otherwise authorization will fail.
Version history
- 0.9.0 - read, write, follow
- 2.4.0 - push
- 2.4.3 - granular scopes #7929
- 2.6.0 - read:reports deprecated (unused stub) #8736/adcf23f
- 2.6.0 - write:conversations added #9009
- 2.9.1 - Admin scopes added #9387
- 3.1.0 - Bookmark scopes added #7107
- 4.1.0 - Added admin scopes for blocks and allows #20918
List of scopes
read
Grants access to read data. Requesting read will also grant child scopes shown in the left column of the table below.
readread:accountsread:blocksread:bookmarksread:favouritesread:filtersread:followsread:listsread:mutesread:notificationsread:searchread:statuses
write
Grants access to write data. Requesting write will also grant child scopes shown in the right column of the table below.
writewrite:accountswrite:blockswrite:bookmarkswrite:conversationswrite:favouriteswrite:filterswrite:followswrite:listswrite:mediawrite:muteswrite:notificationswrite:reportswrite:statuses
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:blocksread:follows,write:followsread:mutes,write:mutes
push
Grants access to [Web Push API subscriptions.]({{< relref "methods/push" >}}) Added in Mastodon 2.4.0.
Admin scopes
Used for moderation API. Added in Mastodon 2.9.1. The following granular scopes are available (note that there is no singular admin scope):
admin:readadmin:read:accountsadmin:read:reportsadmin:read:domain_allowsadmin:read:domain_blocksadmin:read:ip_blocksadmin:read:email_domain_blocksadmin:read:canonical_email_blocks
admin:writeadmin:write:accountsadmin:write:reportsadmin:write:domain_allowsadmin:write:domain_blocksadmin:write:ip_blocksadmin:write:email_domain_blocksadmin:write:canonical_email_blocks
Granular scopes
| read | write |
|---|---|
| read:accounts | write:accounts |
| read:blocks | write:blocks |
| read:bookmarks | write:bookmarks |
| write:conversations | |
| read:favourites | write:favourites |
| read:filters | write:filters |
| read:follows | write:follows |
| read:lists | write:lists |
| write:media | |
| read:mutes | write:mutes |
| read:notifications | write:notifications |
| write:reports | |
| read:search | |
| read:statuses | write:statuses |
| admin:read | admin:write |
|---|---|
| admin:read:accounts | admin:write:accounts |
| admin:read:reports | admin:write:reports |
| admin:read:domain_allows | admin:write:domain_allows |
| admin:read:domain_blocks | admin:write:domain_blocks |
| admin:read:ip_blocks | admin:write:ip_blocks |
| admin:read:email_domain_blocks | admin:write:email_domain_blocks |
| admin:read:canonical_email_blocks | admin:write:canonical_email_blocks |