Logging in with an account
How to obtain authorization from a user and perform actions on their behalf.
When we registered our app and when we will 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.
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 for a full list of scopes. Each API method’s documentation will also specify the OAuth access level and scope required to call it.
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_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_idwas obtained when registering our application.
scopemust be a subset of our registered app’s registered scopes. It is a good idea to only request what you need. See OAuth Scopes for more information.
redirect_uriis 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
codeand can be logged by your request handler. See the response section of the API method documentation for more information on this.
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 'client_id=your_client_id_here' \ -F 'client_secret=your_client_secret_here' \ -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \ -F 'grant_type=authorization_code' \ -F 'code=user_authzcode_here' \ -F 'scope=read write push' \ https://mastodon.example/oauth/token
Note the following:
client_secretwere provided in the response text when you registered your application.
redirect_urimust be one of the URIs defined when registering the application.
- We are requesting a
authorization_code, which still defaults to giving us the
readscope. However, while authorizing our user, we requested a certain
scope– pass the exact same value here.
codecan 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. 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:
curl \ -H 'Authorization: Bearer our_access_token_here' \ 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.
- See /api/v1/notifications for managing a user’s notifications.
- See /api/v1/push for subscribing to push notifications.
- See /api/v2/search for querying resources.
- See /api/v1/suggestions for suggested accounts to follow.
Use 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 December 14, 2022 · Improve this page