Mastodon — how to connect

Posts text statuses (up to 4 images or 1 video) to any Mastodon-compatible federated instance. No app setup here — paste your instance URL and an access token with the write:statuses scope when you add the account.

The app only needs your instance's URL plus a personal access token — you register a small application in your own account settings to get one; no Mastodon-side approval or review is required.

Before you start

An account (and login access) on the Mastodon instance you want to post from — this is your "home instance"; there's no third-party app-review step, but you must be able to reach that instance's settings.
A generated access token: on the instance, go to Preferences → Development → New Application, then copy the resulting access token (do not use the app's client key/secret — this adapter takes the bearer token directly).
The token's application must include the write:statuses scope (verify_credentials only needs read/read:accounts, which most default app scopes already include); if you'll post images or video, also include write:media — Mastodon scopes are fixed at app-creation time and can't be edited after the fact.
The exact instance domain (e.g. mastodon.social or your self-hosted domain) — posting is federated per-account, so the wrong or a redirect/alias domain for the same account will fail even with a valid token.

Step by step

1
Log in to your Mastodon instance
Sign in at your instance's web address (e.g. https://mastodon.social) with the account you want to publish from.
Open
2
Open Development settings
Go to Preferences → Development, where your instance lists and manages your registered applications and their tokens.
3
Create a new application
Click New Application, give it any name (e.g. "Social Manager"), and leave the default redirect URI as-is.
4
Grant the write:statuses scope
Under Scopes, select at minimum write:statuses (the only permission this integration needs) for least privilege.
5
Save and open the application
Submit the form, then click into the newly created application to reveal Your access token.
6
Paste both values into the app
Copy your instance URL (e.g. https://mastodon.social) into Instance URL and the access token string into Access token (write:statuses).

Paste when you connect

Instance URL
The bare instance domain your account lives on (e.g. https://mastodon.social) — not a profile URL or /@handle path.
Access token (write:statuses)secret
On your instance: Preferences → Development → New Application → open it → "Your access token". Scopes are fixed at creation — pick write:statuses (+ write:media for images).

Good to know

No app-level OAuth keys are needed here — the adapter has no configFields(), only two credentialFields(): Instance URL and Access token (write:statuses).
The token is tied to whichever scopes you pick at app-creation time; selecting more than write:statuses still works but is broader than necessary.
Works on any Mastodon-compatible instance (Mastodon itself or forks like Glitch-soc), since this is the standard REST/OAuth token flow, not a platform-run app-review process — there's no waiting period.
Default character limit is treated as 500 by the adapter, but some instances allow more; this is a conservative default, not a hard API constraint.
If the token is revoked or the application is deleted from Preferences → Development, publishing fails with an auth error immediately — tokens otherwise don't expire on their own.

Troubleshooting

Connecting the account fails immediately with a 401 from verify_credentials ("invalid token"/"unauthorized").: The token was mistyped/truncated on paste, belongs to a different instance than the URL entered, or its application was deleted/revoked on the instance. Regenerate a fresh token via Preferences → Development on that exact instance and re-paste it in full.
Connect succeeds (verify_credentials works) but publishing a status or uploading media fails with a 422/403 scope error.: The application behind the token wasn't created with write:statuses (and write:media for images/video). Mastodon won't let you add scopes to an existing app/token — create a new application with the needed scopes and reconnect with the new token.
Posts start failing with HTTP 429 during bursts of scheduled/bulk posting.: Mastodon rate-limits per account/token at roughly 300 requests per 5 minutes by default (lower on some instances). Space out sends and retry with backoff; this adapter's idempotency-key makes retries safe (Mastodon dedupes near-identical retries for about an hour).
Connect fails or posts go to the wrong account even though the token looks valid.: The instance field must be the bare domain (e.g. mastodon.social), not a profile URL, custom short domain, or a path like /@handle. Confirm by opening https://<instance>/api/v1/instance directly in a browser before pasting the URL in.

Mastodon developer docs

Before you start

An account (and login access) on the Mastodon instance you want to post from — this is your "home instance"; there's no third-party app-review step, but you must be able to reach that instance's settings.

A generated access token: on the instance, go to Preferences → Development → New Application, then copy the resulting access token (do not use the app's client key/secret — this adapter takes the bearer token directly).

The token's application must include the write:statuses scope (verify_credentials only needs read/read:accounts, which most default app scopes already include); if you'll post images or video, also include write:media — Mastodon scopes are fixed at app-creation time and can't be edited after the fact.

The exact instance domain (e.g. mastodon.social or your self-hosted domain) — posting is federated per-account, so the wrong or a redirect/alias domain for the same account will fail even with a valid token.

Step by step

Open

Open Development settings

Go to Preferences → Development, where your instance lists and manages your registered applications and their tokens.

Create a new application

Click New Application, give it any name (e.g. "Social Manager"), and leave the default redirect URI as-is.

Grant the write:statuses scope

Under Scopes, select at minimum write:statuses (the only permission this integration needs) for least privilege.

Save and open the application

Submit the form, then click into the newly created application to reveal Your access token.

Paste both values into the app

Copy your instance URL (e.g. https://mastodon.social) into Instance URL and the access token string into Access token (write:statuses).

Paste when you connect

Instance URL

The bare instance domain your account lives on (e.g. https://mastodon.social) — not a profile URL or /@handle path.

Access token (write:statuses)secret

On your instance: Preferences → Development → New Application → open it → "Your access token". Scopes are fixed at creation — pick write:statuses (+ write:media for images).

Good to know

No app-level OAuth keys are needed here — the adapter has no configFields(), only two credentialFields(): Instance URL and Access token (write:statuses).

The token is tied to whichever scopes you pick at app-creation time; selecting more than write:statuses still works but is broader than necessary.

Works on any Mastodon-compatible instance (Mastodon itself or forks like Glitch-soc), since this is the standard REST/OAuth token flow, not a platform-run app-review process — there's no waiting period.

Default character limit is treated as 500 by the adapter, but some instances allow more; this is a conservative default, not a hard API constraint.

If the token is revoked or the application is deleted from Preferences → Development, publishing fails with an auth error immediately — tokens otherwise don't expire on their own.

Troubleshooting

Connecting the account fails immediately with a 401 from verify_credentials ("invalid token"/"unauthorized").

The token was mistyped/truncated on paste, belongs to a different instance than the URL entered, or its application was deleted/revoked on the instance. Regenerate a fresh token via Preferences → Development on that exact instance and re-paste it in full.

Connect succeeds (verify_credentials works) but publishing a status or uploading media fails with a 422/403 scope error.

The application behind the token wasn't created with write:statuses (and write:media for images/video). Mastodon won't let you add scopes to an existing app/token — create a new application with the needed scopes and reconnect with the new token.

Posts start failing with HTTP 429 during bursts of scheduled/bulk posting.

Mastodon rate-limits per account/token at roughly 300 requests per 5 minutes by default (lower on some instances). Space out sends and retry with backoff; this adapter's idempotency-key makes retries safe (Mastodon dedupes near-identical retries for about an hour).

Connect fails or posts go to the wrong account even though the token looks valid.

The instance field must be the bare domain (e.g. mastodon.social), not a profile URL, custom short domain, or a path like /@handle. Confirm by opening https://<instance>/api/v1/instance directly in a browser before pasting the URL in.