Skip to content

Get Mastodon posting credentials

Let keryx auth mastodon sign in to your account on any Mastodon instance so keryx publish can post a text-and-image announcement there (spec 0060 D17). There is no developer console to visit: keryx registers itself as an app on the instance over the API, and the token it gets does not expire. Two minutes.

1. Sign keryx in

keryx auth mastodon

The first run asks for the instance (mastodon.social, or the full https:// URL) and records it as platforms.mastodon.instance. It then:

  1. Registers an app named keryx on the instance, with the scopes read:accounts write:media write:statuses, and keeps its client id in config and its client secret with the credentials (keychain, else the accounts file). Later runs reuse it.
  2. Opens the consent page (or prints the URL) and captures the code on the plain-http loopback, http://127.0.0.1:3764/ (the same port as the Meta platforms, so one ssh forward serves every auth). The code can also be pasted: the instance shows it when the browser cannot reach the loopback.
  3. Swaps the code for the user token, verifies it, stores it, and reads the instance's posting limits into platforms.mastodon.constraints. {text_cap,link_weight}, because each instance sets its own.

In CI, MASTODON_ACCESS_TOKEN in the environment is the token.

2. What a post looks like there

  • A status: the text, the hashtags on a new line, and the link on another, held together to the instance's cap (500 characters on mastodon.social, with a link counting 23 whatever its length).
  • Up to four images, uploaded as bytes with their alt text as the description. No public URL is needed, so an article need not be live.
  • Visibility is public unless platforms.mastodon.visibility says unlisted, private or direct.
  • No video.

Refresh

Nothing to rotate: keryx auth refresh verifies the token with the instance and reports healthy, or reauth-required when the instance rejects it (the app was revoked under Preferences → Account → Authorized apps).