Mastodon API Setup

Mastodon's federated model means every instance issues its own OAuth app credentials. Sosyabot handles this automatically: on the first connect to a new instance the backend calls POST <instance>/api/v1/apps and stores the resulting client_id/client_secret in the mastodon_apps collection. End-users just type their instance domain and approve.

The admin form at /admin/api-integration/mastodon only matters for legacy single-instance accounts that pre-date the dynamic registration system.

Overview

Form field	Options key	Use
Default instance URL (legacy)	mastodon_instance-url	Fallback for legacy connections that didn't carry an instance domain.
Default client key (legacy)	mastodon_client-key	Same legacy fallback.
Default client secret (legacy)	mastodon_client-secret	Same.
Status	mastodon_integration_status	Master enable/disable.

ENV fallback: MASTODON_INSTANCE_URL, MASTODON_CLIENT_KEY, MASTODON_CLIENT_SECRET.

The OAuth callback URL Sosyabot sends to every instance is:

https://app.sosyabot.com/api/v1/auth/mastodon/callback

How dynamic registration works

When a user starts a Mastodon connect with ?instance=mastodon.social (or any other domain), Sosyabot:

1. Looks up mastodon.social in the mastodon_apps collection.
2. If not found, calls POST https://mastodon.social/api/v1/apps with the Sosyabot app name + redirect URI + scopes (read write).
3. Caches the returned client_id + client_secret in mastodon_apps.
4. Redirects the user to https://mastodon.social/oauth/authorize?....
5. On callback, exchanges the code for an access token.

Each instance gets a separate registration; subsequent connects to the same instance reuse the cached credentials.

When you need to fill the admin fields

Almost never. Skip this whole page unless:

• You are migrating data from a pre-Sosyabot system that had hard-coded single-instance credentials, OR
• You want to seed credentials for an instance whose dynamic registration is broken.

For everyone else, leave the admin fields empty — the dynamic flow handles everything.

Pasting into Sosyabot admin panel (legacy only)

/admin/api-integration/mastodon:

1. Default instance URL: e.g. https://mastodon.social.
2. Default client key: the legacy client_id.
3. Default client secret: the legacy client_secret.
4. Status: Enable.
5. Save.

There is no Test button.

Verification

Have a user connect to a real Mastodon instance from /app/channels. The first time anyone in your instance connects to that domain, you'll see a row appear in the mastodon_apps collection — that confirms dynamic registration works.

Troubleshooting

Symptom	Cause	Fix
Mastodon registration failed: 503 on first connect to a new instance	The instance is down or rejected the registration	Try a different instance; check the instance's status page.
redirect_uri_mismatch after upgrading Sosyabot's BASE_URL	Each cached mastodon_apps row is pinned to the old URL	Drop the affected rows from mastodon_apps; the next connect re-registers with the new URL.
User wants to use a private/whitelisted instance	Sosyabot's app name might not be allowed	Check the instance's policy on app registration; some require manual approval.

ENV fallback

MASTODON_INSTANCE_URL=https://mastodon.social   # legacy default
MASTODON_CLIENT_KEY=
MASTODON_CLIENT_SECRET=

After editing .env run ./service.sh restart api.

Related

OAuth Credentials overview

Mastodon user-side connect

OAuth Callback URLs