Mastodon
  • What is Mastodon?
  • Using Mastodon
    • Signing up for an account
    • Setting up your profile
    • Posting to your profile
    • Using the network features
    • Dealing with unwanted content
    • Promoting yourself and others
    • Set your preferences
    • More settings
    • Using Mastodon externally
    • Moving or leaving accounts
    • Running your own server
  • Running Mastodon
    • Preparing your machine
    • Installing from source
    • Configuring your environment
    • Configuring full-text search
    • Installing optional features
      • Object storage
      • Onion services
      • Captcha
      • Single Sign On
    • Setting up your new instance
    • Using the admin CLI
    • Upgrading to a new release
    • Backing up your server
    • Migrating to a new machine
    • Scaling up your server
    • Moderation actions
    • Troubleshooting errors
      • Database index corruption
    • Roles
  • Developing Mastodon apps
    • Getting started with the API
    • Playing with public data
    • Obtaining client app access
    • Logging in with an account
    • Libraries and implementations
  • Contributing to Mastodon
    • Technical overview
    • Setting up a dev environment
    • Code structure
    • Routes
    • Bug bounties and responsible disclosure
  • Spec compliance
    • ActivityPub
    • WebFinger
    • Security
    • Microformats
    • OAuth
    • Bearcaps
  • REST API
    • Datetime formats
    • Guidelines and best practices
    • OAuth Tokens
    • OAuth Scopes
    • Rate limits
  • API Methods
    • apps
      • oauth
      • emails
    • accounts
      • bookmarks
      • favourites
      • mutes
      • blocks
      • domain_blocks
      • filters
      • reports
      • follow_requests
      • endorsements
      • featured_tags
      • preferences
      • followed_tags
      • suggestions
      • tags
    • profile
    • statuses
      • media
      • polls
      • scheduled_statuses
    • timelines
      • conversations
      • lists
      • markers
      • streaming
    • grouped notifications
    • notifications
      • push
    • search
    • instance
      • trends
      • directory
      • custom_emojis
      • announcements
    • admin
      • accounts
      • canonical_email_blocks
      • dimensions
      • domain_allows
      • domain_blocks
      • email_domain_blocks
      • ip_blocks
      • measures
      • reports
      • retention
      • trends
    • proofs
    • oembed
  • API Entities
    • Account
    • AccountWarning
    • Admin::Account
    • Admin::CanonicalEmailBlock
    • Admin::Cohort
    • Admin::Dimension
    • Admin::DomainAllow
    • Admin::DomainBlock
    • Admin::EmailDomainBlock
    • Admin::Ip
    • Admin::IpBlock
    • Admin::Measure
    • Admin::Report
    • Announcement
    • Appeal
    • Application
    • Context
    • Conversation
    • CustomEmoji
    • DomainBlock
    • Error
    • ExtendedDescription
    • FamiliarFollowers
    • FeaturedTag
    • Filter
    • FilterKeyword
    • FilterResult
    • FilterStatus
    • IdentityProof
    • Instance
    • List
    • Marker
    • MediaAttachment
    • Notification
    • NotificationPolicy
    • NotificationRequest
    • Poll
    • Preferences
    • PreviewCard
    • PreviewCardAuthor
    • PrivacyPolicy
    • Quote
    • Reaction
    • Relationship
    • RelationshipSeveranceEvent
    • Report
    • Role
    • Rule
    • ScheduledStatus
    • Search
    • ShallowQuote
    • Status
    • StatusEdit
    • StatusSource
    • Suggestion
    • Tag
    • TermsOfService
    • Token
    • Translation
    • V1::Filter
    • V1::Instance
    • V1::NotificationPolicy
    • WebPushSubscription

Logging in with an account

How to obtain authorization from a user and perform actions on their behalf.

    • Scopes explained
    • Example authorization code flow
      • Client ID and secret
      • Authorize the user
      • Obtain the token
    • Performing actions as the authorized user
      • Publish and delete statuses
      • Interact with timelines
      • Interact with other users
      • Receive notifications
      • Discovery features
      • User safety features
      • Manage account info

Scopes explained

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

See OAuth Scopes for a full list of scopes. Each API method’s documentation will also specify the OAuth token type 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.

OAuth Scopes

Example authorization code flow

This is similar to the authentication flow from before, but this time, we need to obtain authorization from a user as well.

Client ID and secret

First, if you have not already registered a client application, then see Creating our application on the previous page or go directly to POST /api/v1/apps for the full documentation of that method. We will need the client_id and client_secret for our application.

Authorize the user

To authorize a user, request GET /oauth/authorize in a browser with the following query parameters:

https://mastodon.example/oauth/authorize
?client_id=CLIENT_ID
&scope=read+write+push
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&response_type=code

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 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 by your request handler for the redirect URI. See the response section of the API method documentation for more information on this.

Treat the code query parameter as if it were a password, you should ensure that it is not logged in request logs.

Obtain the token

Now that we have an authorization code, let’s obtain an access token that will authenticate our requests as the authorized user. To do so, use POST /oauth/token like before, but pass the authorization code we just obtained:

curl -X POST \
	-F 'grant_type=authorization_code' \
	-F 'client_id=your_client_id_here' \
	-F 'client_secret=your_client_secret_here' \
	-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
	-F 'code=user_authzcode_here' \
	https://mastodon.example/oauth/token

Note the following:

  • We are requesting a grant_type of authorization_code
  • 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.
  • 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 step.

The response of this method is a Token entity. We will need the access_token value. Once you have the access token, save it in your local cache.

The scope of resulting Access Token will be the scopes approved during the Authorization Request

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.

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:

curl \
	-H 'Authorization: Bearer <access_token>' \
	https://mastodon.example/api/v1/accounts/verify_credentials

If we’ve obtained our token and formatted our request correctly, we should see our details returned to us as an Account entity, with the source parameter included.

Performing actions as the authorized user

With our OAuth token for the authorized user, we can now perform any action as that user that is within our token’s scope.

Publish and delete statuses

  • See POST /api/v1/statuses for how to create statuses.
    • See /api/v1/media for creating media attachments.
    • See /api/v1/scheduled_statuses for managing scheduled statuses.

Interact with timelines

  • See /api/v1/timelines for accessing timelines.
  • See /api/v1/markers for saving and loading positions in timelines.
  • See /api/v1/statuses for performing actions on statuses.
    • See /api/v1/polls for viewing and voting on polls.
  • See /api/v1/lists for obtaining list IDs to use with GET /api/v1/timelines/list/:list_id.
  • See /api/v1/conversations for obtaining direct conversations.
  • See /api/v1/favourites for listing favourites.
  • See /api/v1/bookmarks for listing bookmarks.

Interact with other users

  • See /api/v1/accounts for performing actions on other users.
  • See /api/v1/follow_requests for handling follow requests.
  • See /api/v1/mutes for listing mutes.
  • See /api/v1/blocks for listing blocks.

Receive notifications

  • See /api/v1/notifications for managing a user’s notifications.
  • See /api/v1/push for subscribing to push notifications.

Discovery features

  • See /api/v2/search for querying resources.
  • See /api/v1/suggestions for suggested accounts to follow.

User safety features

  • See /api/v1/filters for managing filtered keywords.
  • See /api/v1/domain_blocks for managing blocked domains.
  • See /api/v1/reports for creating reports.
  • See /api/v1/admin for moderator actions.

Manage account info

  • See /api/v1/endorsements for managing a user profile’s featured accounts.
  • See /api/v1/featured_tags for managing a user profile’s featured hashtags.
  • See /api/v1/preferences for reading user preferences.

Last updated March 10, 2025 · Improve this page

Sponsored by

Dotcom-Monitor LoadView Stephen Tures Swayable SponsorMotion

Join Mastodon · Blog ·

View source · CC BY-SA 4.0 · Imprint