Mastodon

Overview

Provider id mastodon. There is no global Mastodon host: the instance you name is the origin of every request, the stored account identity and the connection. The provider registers an application on that instance, runs the authorization-code flow with PKCE, and publishes one text status.

Requirements

• The base URL of your instance, for example https://mastodon.social.
• A redirect URI that the authorization step can return to.
• An authorization scope list that includes everything the flow needs later.

The instance's authorize endpoint must be given every scope that is requested afterwards; otherwise it refuses with invalid_scope and issues no token at all.

Credentials

There is no credential input schema for this provider: the accepted credential object is empty, and the connection is completed through browser authorization instead. The client id, client secret and PKCE verifier stay inside the connection's private state and are never copied into a preview, a write outcome or an error.

Connect

{
  "type": "start",
  "provider": "mastodon",
  "options": {
    "instance": "https://mastodon.social",
    "redirectUri": "https://example.com/oauth/callback/mastodon",
    "scopes": ["read:accounts", "write:statuses"]
  }
}

syndroo connect --input connect.json --json

instance, redirectUri and scopes are required; clientId and clientSecret are optional for a caller that already registered an application. The start step returns an authorization action that a browser completes on the instance.

The start step returns an authorization action that a browser completes on the instance, and the local CLI completes that OAuth callback itself, with --redirect-uri and a controlling terminal or with --callback-url -, as the credential reference describes. That local callback path is fixture-tested against local servers only; no live Mastodon account was connected.

First publish

{
  "type": "prepare",
  "content": { "text": "Hello from Syndroo." },
  "targets": [{ "provider": "mastodon", "options": { "visibility": "public" } }]
}

syndroo publish --input post.json --json

Publishing is one POST /api/v1/statuses with a deterministic Idempotency-Key header. The server documents that key as stored for up to one hour and returning the saved response on reuse. That is a provider capability, not permission to retry: Syndroo still reports an unknown write as unknown and never reclassifies it.

Capabilities

The manifest declares text. The character limit is a property of the instance, not a global number: the provider reads it from GET /api/v2/instance during connect and enforces it when the content is frozen. An unreadable limit fails closed instead of assuming a default, so no limit is printed here.

Options

PKCE is verified for this provider and is mandatory for native clients: the provider uses the S256 challenge method. Refresh tokens exist only when an instance enables expiring tokens, so the provider treats them as a per-instance capability rather than a global promise.

Troubleshooting

Errors use a generic { "error": "..." } shape, and validation failures such as blank text are reported as 422. UNRESOLVED. The full error entity field list was not confirmed, so this guide does not enumerate one.

Revoke and security

Revocation is documented and verified: POST /oauth/revoke with the client id, client secret and token returns 200 with no body. Removing the app from your instance settings achieves the same, and disconnecting removes the local record:

syndroo connect --disconnect <connectionId>