Mastodon

OAuth 2.0, per instance. Each Mastodon server requires its own app registration. On first connect to a new instance, Sosyabot calls ${instance}/api/v1/apps to register itself and stores the resulting client_id/client_secret in the MastodonApps collection.

Authentication at a glance

Field	Value
Auth model	OAuth 2.0
Required ENV	MASTODON_INSTANCE_URL
Callback URL	${BASE_URL}/api/v1/auth/mastodon/callback
Scopes / permissions	read, write
Auto token refresh	No — manual reconnect on expiry

ENV details

MASTODON_INSTANCE_URL is a fallback for legacy connections that pre-date per-instance storage. Modern flows ignore it and read the instance from the connect URL (?instance=<domain>).

How to connect

1. Open Connections → Mastodon → Connect.
2. Type the instance domain (e.g. mastodon.social).
3. Sosyabot redirects to that instance, you grant read write scopes, and you bounce back.

Token refresh

Mastodon access tokens are long-lived and not refreshed by the queue.

Notes

• Pass the target instance as a query parameter when initiating connect: GET /api/v1/auth/mastodon?instance=mastodon.social.
• Each instance registers a separate client; the app name shows up as Sosyabot in the user's instance Preferences → Authorized applications.
• The push scope is not requested in this build — Mastodon notifications come through the standard timeline API.

Troubleshooting

If the channel shows needs_reconnect, the access token was rejected by Mastodon. Common causes:

• The user revoked Sosyabot's authorization on the platform.
• The platform invalidated the token (password change, security event).
• Your OAuth app credentials rotated and the existing tokens no longer match.

Re-run the connect flow above. See Troubleshooting for the workspace-wide checklist.

Related

Connections Overview

Composer

OAuth Callback URLs