Skip to main content

The Complete Guide to ActivityPub Development in 2026

· 6 min read
SocialDocs Team
SocialDocs Team
Documentation Team

ActivityPub connects about 13.8 million registered accounts (roughly 1.37 million active monthly) across Mastodon, Misskey, Pixelfed, PeerTube, Lemmy and many other servers, according to FediDB in October 2026. This guide is the 2026 update of our 2025 guide: what you need to build, what changed this year, and which tools to use.

The short version​

  • Use a maintained library for federation plumbing. Request signing and verification, origin checks and safe fetching are where most security bugs live. Fedify and Mastodon both shipped fixes for these bug classes in 2026.
  • Target current Mastodon behaviour (4.7 as of October 2026), because most of the network runs Mastodon, but test against at least one other server too.
  • Treat the actor id as identity, not the handle. Mastodon 4.7 made this switch.

Core concepts​

An actor (usually a Person, Group or Service) has an inbox and an outbox. Servers federate by POSTing activities (Create, Follow, Like, Announce, Delete, Undo…) to each other's inboxes, signed with the sending actor's key. Discovery from a handle like @alice@example.com goes through WebFinger.

{
  "@context": ["https://www.w3.org/ns/activitystreams", "https://w3id.org/security/v1"],
  "type": "Person",
  "id": "https://example.com/users/alice",
  "preferredUsername": "alice",
  "inbox": "https://example.com/users/alice/inbox",
  "outbox": "https://example.com/users/alice/outbox",
  "followers": "https://example.com/users/alice/followers",
  "publicKey": {
    "id": "https://example.com/users/alice#main-key",
    "owner": "https://example.com/users/alice",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n..."
  }
}

Serve actors and objects as application/activity+json (Mastodon ignores plain application/json) and WebFinger as application/jrd+json. Start with Core Concepts and Understanding Federation.

What changed in 2025–2026​

ChangeWhy it matters
Quote posts in Mastodon 4.5 (FEP-044f)Quotes need the author's consent via QuoteRequest / QuoteAuthorization and a quote policy
Collections in Mastodon 4.6 (FEP-7aa9)Curated, opt-in lists of accounts
RFC 9421 HTTP Message Signatures — Mastodon 4.7 sends them as a fallback to the older draft, and supports Ed25519Plan to verify both the legacy draft-cavage format and RFC 9421
Object Integrity Proofs — Mastodon 4.7 verifies FEP-8b32Objects can carry their own signatures
Actor id as primary identifier — Mastodon 4.7Remote accounts can change handles without becoming new accounts
FEP-7628 (Move actor) is FINAL (August 2026)Standardised account migration
W3C Social Web Working Group chartered (January 2026)Backwards-compatible updates to ActivityPub and Activity Streams are in progress in the Editor's Draft; none published yet

Details: Mastodon 4.6 and Mastodon 4.7 release posts, and our October 2026 changelog.

Receiving activities safely​

danger

The inbox is the most security-sensitive part of an ActivityPub server. Several code samples elsewhere on this site are known to be unsafe; see issue #37. Prefer a maintained library's verification over hand-written code.

Whatever you use, every inbound POST must pass these checks before you act on it:

  1. The signature verifies, and it covers at least (request-target), host, date and digest (or the RFC 9421 equivalents, including content-digest).
  2. The digest matches the raw request body, not a re-serialised copy of the parsed JSON.
  3. The Date is recent. Mastodon treats a signature without an explicit expiry as valid for 5 minutes after it was created, plus a 1-hour clock-skew margin, so roughly 65 minutes in total; it also rejects signatures dated more than 1 hour in the future, and caps any explicit expiry at 12 hours (signed_request.rb).
  4. The key's owner is the activity's actor. A valid signature from one actor must not authorise an activity claiming to be from another.
  5. Embedded objects come from the same origin as the actor, or you re-fetch them from their own origin before trusting them.
  6. Every remote fetch is SSRF-safe: block private and loopback addresses, re-check after redirects, and cap response sizes.
  7. Remote HTML is sanitised before you render it.

Libraries worth using (October 2026)​

LanguageLibraryStatus
TypeScript / JavaScriptFedifyActive (2.4.x); includes a CLI for debugging
Rustactivitypub-federation (used by Lemmy)Active (0.6.6, October 2026)
PythonapkitActive (0.3.x)
Gogo-ap/activitypub (vocabulary)Active

Avoid starting new projects on activitypub-express (last release February 2024), go-fed/activity (no commits since 2022) or little-boxes (archived). Browse the library pages for more options.

Testing interop​

  1. Expose your dev server over public HTTPS with fedify tunnel or ngrok.
  2. Inspect what remote servers see with BrowserPub or fedify lookup.
  3. Use fedify inbox to get a throwaway actor that follows you and shows what your server sends.
  4. Follow your test account from a real, current Mastodon and at least one other server (GoToSocial, Misskey, Lemmy…).

See Testing & Debugging Tools and Testing Your Implementation.

Platform quirks to plan for​

PlatformWhat to know
MastodonRequires signed Digest on POST; serve application/activity+json; supports quote posts and collections
LemmyCommunities are Group actors; 1.0 (with API v4) is in beta, 0.19.x is stable
PeerTubeVideos are Video objects with PeerTube-specific extensions
PixelfedPosts with images arrive as objects with attachments

Guides: Mastodon, Lemmy, PeerTube, Pixelfed.

Where the community is​

Found an error? Open an issue — we fix and log corrections.