documentation/oauth-scopes.md at 60d552157ea43475b3128ff6b103fa0d3b5f59dc

mirror of https://github.com/mastodon/documentation synced 2025-04-11 22:56:17 +02:00

* add rules

* join date on profiles

* deprecate follow scope

* deprecate identity proofs

* familiar followers

* use definition lists instead of tables for defining activitypub properties

* reformat notifications page into markdown

* fix broken links to publicKey header

* Application website is now nullable

* update environment variables added and removed

* fix typo

* fix heading level

* min_id and max_id can be used at the same time (3.3)

* fix typo

* new tootctl options

* reformat tootctl page to use definition lists for params

* add rules and configuration to Instance

* fix typo

* refactor instance api page

* 3.3.0 duration on mutes

* 3.3.0 mute_expires_at

* improve section headings

* 3.4.0 resend email confirmation api

* 3.4.0 policy on push subscriptions

* 3.4.0 add details to account registration error

* refactor accounts api page and start adding relrefs to entity pages

* 3.4.0 accounts/lookup api

* add see also to accounts methods

* add more see-also links

* 3.5.0 appeal mod decisions

* 3.5.0 reformat reports and add category/rule_ids params

* document report entity and missing responses

* fix typos

* fix relrefs and url schema, add aliases to old urls

* add archetypes for new methods/entities

* update archetypes with see-also stubs

* clearer presentation of rate limits

* announcements api methods

* refactor apps methods

* refactor bookmarks methods + some anchors

* refactor conversations methods

* custom_emojis methods refactor

* anchors

* refactor directory methods

* refactor domain_blocks methods

* add see also to emails methods

* fix page relref shortcodes to specific methods + refactor endorsements methods

* min_id max_id

* refactor favourites methods

* refactor featured_tags methods

* refactor filters methods, make path params consistent, i18n required shortcode

* follow_requests methods

* lists methods

* markers methods

* forgot to add entity links

* media methods, also fix formatting of some json errors

* mutes methods, add more see-also links

* oembed methods

* preferences methods

* proofs methods

* push methods

* suggestions methods

* 3.5.0 add new trend types, fix formatting

* refactor streaming methods

* refactor oauth methods

* note that streaming api casts payload to string

* refactor search methods

* refactor polls methods

* remove unnecessary link

* reformat scheduled_statuses methods

* reformat timelines methods

* reformat statuses methods

* 3.5.0 editing statuses

* consistent use of array brackets in form data parameters

* update dev setup guide, add vagrant and clean up text

* add admin/accounts methods

* 3.6 role entity

* admin/accounts methods v2

* minor fix

* stub admin/reports methods

* document admin reports

* add 403 example to methods archetype

* cleanup entities for admin reports and add new attrs

* 3.6.0 domain allows methods + normalize admin entity namespace

* fix search-and-replace error

* add aliases for admin entities

* 3.6.0 canonical email blocks entity

* 3.5.0 admin/retention api

* 3.5.0 add admin::ip doc

* 3.5.0 admin/reports

* 3.6.0 admin/domain_allows

* 3.5.0 admin/dimensions

* 3.6.0 permissions and roles

* minor formatting fix

* add anchor link to headings

* checkpoint

* add update commands to dev env setup guide

* change mentions of v3.6 to v4.0

* tootctl now uses custom roles

* fix formatting

* v2 instance api

* update frontmatter, add better titles to pages

* minor wording change

* consistency

* add more aliases

* add placeholders and WIP notices

* explain link pagination and stub out todos

* switch baseURL to https

* 422 on reports with rules but category!=violation

* document bug fixes

* fix typo

* remove duplicate API method definition

* s/tootsuite/mastodon for github links

* remove unnecessary escaping

* s/tootsuite/mastodon in Entity archetype

* add missing nullable shortcode

* clarify oauth scope when requesting a user token

* api/v2/media now synchronous for images

* DISALLOW_UNAUTHENTICATED_API_ACCESS

* add undocumented env variables

* add instance domain blocks and extended description api

* add SMTP_ENABLE_STARTTLS

* add description to SMTP_ENABLE_STARTTLS

* take suggestions from open PRs

* normalize links and flavour language

* Fully document streaming API based on source code

* Add mention of MIME types

* bump to ruby 3.0.4

* clarify how to check on async media processing

* validation of replies_policy

* remove TODOs on admin account action

* EmailDomainBlocks

* IpBlocks

* Admin::DomainBlock

* remove TODOs

* following hashtags

* followed_tags

* remove reference to unused parameter

* add new oauth scopes for admin blocks and allows

* fix command signature for i18n-tasks normalize

* reformat code structure page

* document fixes for following tags (assume 4.0.3)

* Add warning about pre-4.0 hardcoded roles

* add note about case sensitivity

* remove use of 'simply' from docs

* remove reference to silencing

* add reference to IDN normalization for verified links

* add lang parameter

2022-11-20 07:34:38 +01:00

4.8 KiB

Raw Blame History

title

description

OAuth Scopes

Defining what you have permission to do with the API

docs

weight	parent
20	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.0.3 - 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.

read
- read:accounts
- read:blocks
- read:bookmarks
- read:favourites
- read:filters
- read:follows
- read:lists
- read:mutes
- read:notifications
- read:search
- read:statuses

`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`

{{< 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

`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: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

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

4.8 KiB Raw Blame History Unescape Escape

OAuth Scopes

Version history

List of scopes

read

write

follow

push

Admin scopes

Granular scopes

4.8 KiB

Raw Blame History

`read`

`write`

`follow`

`push`