Simple Mastodon Oauth

2017-04-19

There seems to be a new kid on the block and it's called Mastodon. It's twitter sans the crap. Well for now, anyways. Actually it seems to be more like the middle ground between IRC and Twitter, if that makes sense. Anyways, many people on my list seem to at least be toying with the idea of jumping ship and it's come to the point where I think I should at least bridge the gap myself.

For now I think the majority will remain on Twitter. It feels like a sinking ship, adding more and more bloat while under pressure from stock holders and without actually ... helping. It's kind of an inevitable turn of events, I guess. But it's a problem when most of your work is tied to that account. Mind you, if Twitter would offer any kind of crap-free subscription model I'd jump right into it. But it seems they're totally not interested in that. Weird.

I'm in the middle of setting up a script that serves as the bridge. When I post something to Twitter it should pick that up and automatically mirror the post to Mastodon. Fairly straightforward stuff.

The first hurdle is authentication. I think Oauth is a unnecessarily bloated piece of dung but you don't really have a choice. Best I can do for you is make this step as easy and transparent as possible.

There are some tools out there that can do this for you but seriously, don't put your user/pass on a site where it does not belong. You don't know what happens with that data. The steps below are super transparent if you have even the slightest idea of html. And even without... These snippets are simple forms that are generated on a blank page from your dev tools. The data is only submitted to Mastodon's api, which you inherently trust with this information, and there is no third party involved.

What you need is your login information and perhaps to know which server you are on. While Twitter has only one server, Mastodon has multiple servers that work together but your account only exists on one.

For a full api reference see https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md

The first step is to "register" your app. This generates a special user/pass account for your app to use. You can leverage the specific access this sub-account has to your account (read/write/follow) and you'll need it to get actual access.

Go to a new tab in the browser, you don't need to be logged into Mastodon (but you can be, all the same). In some browsers you may need to go to about:blank but in most it will just work. Open the dev tools, generally F12 will work otherwise just look it up from the menu if you don't know although in that case you may want to just turn back now, this guide was not meant for you.

In the dev tools paste the following. This will create a dead simple web page in the current page with a form (it's a hack, you'll excuse me). Do NOT use your Mastodon user name and password here! It's for the app only (and you won't really use it, anyways).

Code:
document.body.innerHTML = `
<style>* {float:left;clear:both; min-width:400px; }</style>
<form method=post action="https://mastodon.social/api/v1/apps">
<input name=client_name value="name_of_the_app">
<input name=client_secret value="password_for_the_app">
<input name=scopes value="read write follow">
<input name=website value="http://optional_app_website">
<input name=redirect_uris value="urn:ietf:wg:oauth:2.0:oob">
<input type=submit>
</form>
`;

This basically registers a new app user/pass which we can use in the next step. At first I thought these apps were tied to an account, but now I realize anyone can anonymously generate these app logins. Okay.

The redirect url is some kind of standardized token to indicate that there is no redirect, so ignore it because the field itself is required.

The response should look something like this:

Code:
{"id":12345,"redirect_uri":"urn:ietf:wg:oauth:2.0:oob","client_id":"HEX1","client_secret":"HEX2"}

Note the HEX1 and HEX2 codes. You'll need to copy (and store) those for the next step.

The next step is to tell Mastodon that this app is allowed to do certain things with your account. This step is called getting the auth token.

Note: In the first step we created an app with certain permissions (in this case all of them; read, write, and follow). Those aren't reflected in the initial response but they are important. When creating the auth token you have to ask for the permission again otherwise you will only get read scope (I guess the default). Super annoying and hard to figure out. The docs, at the time of writing, do not mention this.

Also important to note is that the field in the first step is called scopes (plural) while in the second step it's called scope (singular). Easy to typo so don't.

In the next step you use the codes above for client and your REAL Mastodon user/pass in the fields. This will ask Mastodon for a token that represents that this app has certain access to your account.

Code:
document.body.innerHTML = `
<style>* {float:left;clear:both; min-width:400px; }</style>
<form method=post action="https://mastodon.social/oauth/token">
<input name=client_id value="HEX1">
<input name=client_secret value="HEX2">
<input name=scope value="read write follow">
<input name=grant_type value=password>
<input name=username value="put real login email here">
<input name=password value="put real password here">
<input type=submit>
</form>
`;

In both cases, the scope(s) field is a space delimited field. At this time only read, write, and follow are valid tokens. I'm sure you can figure out what does what yourself.

The response should look something like this:

Code:
{"access_token":"HEX3","token_type":"bearer","scope":"read write follow","created_at":123456}

If you get a redirect instead of a JSON it probably means your authenthication failed.

The HEX3 code is your auth token. From here on out this is the only thing you need to post stuff to your account under the hood of your app. You can revoke this token at any time and recreate it. You can also generate a stricter token, for example to only post messages or to read your timeline.

If your token is ever stolen the thief can only do the things to your account that the app had access to. That may be a lot but it cannot be used to access or change your password or to delete the account. You can see an overview of these tokens on a preference page and revoke keys there. I'm not sure if there's a special page for each app. I would expect there to be one, and otherwise eventually :)

Here is an example to get your timeline (as JSON):

Code:
document.body.innerHTML = `
<style>* {float:left;clear:both; min-width:400px; }</style>
<form method=get action="https://mastodon.social/api/v1/timelines/home">
<input name=access_token value="HEX3">
<input type=submit>
</form>
`;

And here is an example of posting a new message, tweet, toot, or canonically called "a status".

Code:
document.body.innerHTML = `
<style>* {float:left;clear:both; min-width:400px; }</style>
<form method=post action="https://mastodon.social/api/v1/statuses">
<input name=access_token value="HEX3">
<input name=status value="test message posted by app">
<input type=submit>
</form>
`;

You should see a fairly simple REST API pattern here. You can create forms for all the api end points mentioned in the docs.

Some api calls need GET, usually when reading stuff, and some need POST, usually when writing/creating/changing stuff. I also see a DELETE for removing a status. Just update the action field of the form accordingly (case insensitive) and the action to the proper api end point.

Of course you'll want to do this more efficiently in an actual script, but at least this should get you going and allow you to experiment with the platform in a pretty straightforward way.

For now I'll stick to Twitter (@kuvos) as it doesn't make sense for me to jump ship yet. But eventually I can either be found at @kuvos or @qfox on Mastodon. But first we have an identity crisis to attend to.

Hope it helps you.