Getting started with Mastodon API

mastodon.md

So you want to use Mastodon API! Great!

Overview

Mastodon API is a simple REST api. What's REST? Not important, it's a kind of HTTP API. What's HTTP? It's what web pages are loaded with and kind of thing that everyone is using these days.

How do you load something from Mastodon? You do request like

curl https://mastodon.example/api/v1/timelines/public

(I will give simple examples with just CURL but you can use any toaster that can make network requests)

And it gives you a bunch of JSON like

[
  {
    "id": "103206804533200177",
    "created_at": "2019-11-26T23:27:31.000Z",
    "visibility": "public",
    "...": "..."
  },
  {
    "id": "103206804086086361",
    "created_at": "2019-11-26T23:27:32.000Z",
    "visibility": "public",
    "...": "..."
  }
]

(this request is described here: docs.joinmastodon.org/methods/timelines)

This will work with some instances but not others, depending on their settings because the request was not authenticated. In order to really use the API we need to get through a bit of boring and annoying code to authenticate the user but it's breeze after that!

Mastodon docs have other examples of public data and how to play with it: docs.joinmastodon.org/client/public.

Logging in

Here are the steps to log in:

• Ask the user what their server/instance is (maybe you already know)
• Figure out if it's a nazi or a terf instance. If it is, show them the Rick Astley video and stop here
• Make request to create an app. Theoretically this has be done only once but no one cares.
• Open/let the user open OAuth page of their instance
• After the user is done you need to get the result somehow and fetch the auth token with the code
• You are done! You can use the token!

Official "soft" docs on this are actually pretty decent: docs.joinmastodon.org/client/authorized. Feel free to refer there for more details.

Creating an app

I will let you figure out how to implement the first two steps and we will pick it up from "create an app" step.

In this and following examples we will assume that you want to authenticate as a user (not just as an app without user) and that you will not use redirect mechanism and will ask user to copy-paste the code instead (this is simpler).

Example:

curl -X POST \
   -F 'client_name=Test Application' \
   -F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
   https://mastodon.example/api/v1/apps

This should give you something like

{
  "id": "597",
  "name": "Test Application",
  "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "...": "..."
}

This is your app and we care only client_id and client_secret. Hold on to them, we need them for the next steps.

Showing Oauth flow to user

Now make an URL by this recipe:

https://mastodon.example/oauth/authorize
?client_id=your_client_id
&client_secret=your_client_secret
&response_type=code
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

(I broke the lines for convenience)

You only need to change your_client_id and your_client_secret to the values from previous step.

Give this URL to the user or open it in browser automatically:

xdg-open https://mastodon.example/oauth/authorize\
?client_id=your_client_id\
&client_secret=your_client_secret\
&response_type=code\
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

It should do all the auth magic and in the end user should get a code. Mastodon calls it "authorization code". Now for the final step.

Getting to token

Remember the code your user ggave you? Now it's time to use it in your final step:

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

You again need to replace your_client_id and your_client_secret and also your_code_from_previous_step.

This should give you something like

{
  "access_token": "MyAAAAAAAAccceesssToooookeeeen",
  "token_type": "Bearer",
  "scope": "read",
  "created_at": 1653937573
}

Hooray! We got our access token. That's the only thing we need from now on, throw away the rest! Now we can do basically anything.

Using the token

Ger your profile? Just add your token as a header!

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

Want to get home timeline?

curl \
    -H 'Authorization: Bearer MyAAAAAAAAccceesssToooookeeeen' \
    https://mastodon.example/api/v1/timelines/home

Read jokes! Post jorts! It's up to you now.

Little Q&A

• Why does my token says scope "read"? Can I change stuff?
  • I didn't specify the scope for simplicity. Docs go into more detail. If you want to do everything when you make URL for the user add parameter &scope=read+write+follow+push.
• This this with copy-pasting the code is weird, I didn't see apps doing that?
  • This is a simpler way to play around with API. To do it "automatically" you would specify something else in redirect_uri but you will need to work with your OS/browser/WebView to make sure you can handle this URL.
• Why do I need to create an app each time?
  • You don't need to, you can reuse your app. Mastodon uses OAuth and OAuth wasn't exactly designed with "many apps - many servers - open API" scenario in mind. It still helps Masto show your app name under posts but this whole dance could be a simplified if we didn't pretend that we do real OAuth.