MASTODON_INSTANCE_URL environment variable. Because Mastodon is federated, each instance runs its own OAuth server — Hayon’s integration is instance-specific.
How Mastodon auth works
Mastodon implements a standard OAuth 2.0 authorization code flow, but scoped to a specific instance:- Hayon redirects you to
{MASTODON_INSTANCE_URL}/oauth/authorizewith thecoderesponse type and the requested scopes. - You authorize on the Mastodon instance.
- The instance redirects back to Hayon’s callback with an authorization code.
- Hayon exchanges the code for an access token via
POST {MASTODON_INSTANCE_URL}/oauth/token. - Hayon fetches your profile from
GET {MASTODON_INSTANCE_URL}/api/v1/accounts/verify_credentials.
Authorization: Bearer {token} headers for all subsequent API calls.
Connecting your Mastodon account
Verify your instance
Confirm that the Mastodon instance configured in your Hayon deployment (
MASTODON_INSTANCE_URL) is the one your account is on. If not, contact your administrator to update the configuration.Open platform settings
In the Hayon dashboard, navigate to Settings > Connected accounts and click Connect next to Mastodon.
Hayon generates the auth URL
Hayon calls
GET /api/platform/mastodon/connect, which constructs an authorization URL pointing to your configured Mastodon instance with the required scopes and your Hayon user ID as the state parameter.Authorize on Mastodon
Your browser opens your Mastodon instance’s authorization page. Review the requested permissions and click Authorize.
Callback and token exchange
Mastodon redirects back to
GET /api/platform/mastodon/callback. Hayon extracts the code and state, exchanges the code for an access token, and fetches your account profile.Profile stored
Your Mastodon username, display name, avatar, account ID, and the instance URL are stored in your
SocialAccount document.Required OAuth scopes
Hayon requests the following Mastodon scopes:| Scope | Purpose |
|---|---|
read | Read account information, home timeline, notifications |
write | Publish posts (statuses), upload media, manage follows |
push | Subscribe to push notifications (for delivery status updates) |
Mastodon’s scope model uses broad top-level scopes (
read, write, push). More granular sub-scopes (e.g. write:statuses, read:accounts) can be used if you want to restrict permissions — update MASTODON_SCOPES in the service if your deployment requires tighter access control.Instance URL requirements
The Mastodon instance URL must meet these requirements:- Must be a reachable HTTPS URL (e.g.
https://mastodon.social). - Must not include a trailing slash — the service appends paths like
/oauth/authorizedirectly. - Must have an OAuth application registered (Hayon reads
MASTODON_CLIENT_KEYandMASTODON_CLIENT_SECRETfrom environment variables). - The registered application’s redirect URI must match
MASTODON_CALLBACK_URL.
To register an OAuth app on a Mastodon instance, go to
{instance_url}/settings/applications and create a new application with the required scopes and redirect URI. The client key and secret are then set as MASTODON_CLIENT_KEY and MASTODON_CLIENT_SECRET in Hayon’s environment.What Hayon stores
| Field | Description |
|---|---|
connected | true once authorized |
instanceUrl | The Mastodon instance URL at time of connection |
accountId | Your numeric Mastodon account ID on the instance |
auth.accessToken | Bearer token for API requests |
profile.handle | Your Mastodon username (without the @instance part) |
profile.displayName | Your Mastodon display name |
profile.avatar | Avatar URL returned by the instance |
Supported post types
Mastodon posts are called statuses. Hayon supports:| Content type | Supported |
|---|---|
| Text statuses | Yes |
| Statuses with images | Yes (up to 4 attachments) |
| Statuses with video | No |
Content warnings (spoiler_text) | No |
| Polls | No |
| Boosting / reblogging | No |
Character limits
Character limits vary by Mastodon instance. The most common default is:- Default limit: 500 characters per status.
- Extended instances: Some instances (e.g.
mastodon.social) allow up to 500 characters; others likefosstodon.orgmatch this default. - Custom instances: Self-hosted instances can configure any limit. Check your instance’s
/api/v1/instanceendpoint for themax_toot_charsfield.
Media constraints
- Image formats: JPEG, PNG, GIF, WebP (instance-dependent).
- Maximum file size: Typically 8–16 MB per file, configured per instance.
- Attachments per status: Up to 4 media attachments.
- Videos: Not currently supported in Hayon’s Mastodon integration.
- Sensitivity flag: Hayon does not currently set the
sensitiveflag on media — this can be added per instance policy.
Refreshing your profile
To refresh your stored Mastodon profile without reconnecting:GET {instanceUrl}/api/v1/accounts/verify_credentials with your stored access token and updates your username, display name, and avatar.
Disconnecting
To disconnect Mastodon, navigate to Settings > Connected accounts and click Disconnect next to Mastodon, or call:connected: false.
Hayon does not revoke the access token on the Mastodon instance when you disconnect. To fully remove Hayon’s access, go to
{instance_url}/settings/applications and revoke the token there.Troubleshooting
Authorization code missing (callback error)
Authorization code missing (callback error)
401 Unauthorized on API calls
401 Unauthorized on API calls
Wrong instance URL
Wrong instance URL
Hayon always connects to the instance configured in
MASTODON_INSTANCE_URL. If your account is on a different instance, you need to update the environment variable and re-register the OAuth application on the correct instance before reconnecting.Profile refresh fails after password change
Profile refresh fails after password change
Changing your Mastodon account password or revoking tokens in your instance settings invalidates the stored access token. Reconnect Mastodon to obtain a new one.