ActivityPub defines a social API that is complementary and interoperable with the ActivityPub federation protocol. This document provides additional requirements for authorization and HTTP access to achieve higher interoperability with client applications.
This is an experimental specification and is undergoing regular revisions.
[[ActivityPub]] defines a read-write application programming interface (API) for social networking in its sections on Objects, Actors, Collections, and Client-to-Server Interactions, called the social API. Servers that implement the social API are social API servers.
This document provides an additional profile of the social API to improve interoperability with API clients. The profile adds responsibilities to the social API server, including support for authorization and HTTP request semantics.
This profile covers a number of different type of client deployment:
This profile covers a number of different client use cases:
In this model, applications act on behalf of, and with the informed consent of, a single actor.
Unless otherwise specified, in this document server means a Social API server.
This profile provides additional restrictions and requirements for the [[ActivityPub]] social API.
Social API servers SHOULD provide unique, dereferenceable https: URIs for ActivityPub object IDs.
Social API servers SHOULD provide an inbox collection that
accepts the GET HTTP method. Social API servers SHOULD allow actors to read their own inbox collection.
Social API servers SHOULD provide an outbox collection that
accepts the POST HTTP method.
Social API servers SHOULD allocate unique, dereferenceable https: URIs for all activities created by client-to-server interactions.
Social API servers SHOULD implement the behaviour defined for all activity types listed in the Client to Server Interactions section.
Social API servers SHOULD support the Create, Update and Delete activity types for these common Web content object types: Article, Audio, Image, Note, Video.
Social API servers SHOULD support the Create, Update and Delete activity types for the Collection and OrderedCollection types.
Social API servers SHOULD support the Add and Remove activity types for these common Web content object types: Article, Audio, Image, Note, Video.
Social API servers SHOULD support the Add and Remove activity types for actor objects.
Social API servers SHOULD support the Update activity type by the authenticated user for their own actor object to change or add properties of the actor.
Social API servers SHOULD store and distribute activities with other types from the Activity Vocabulary or extension vocabularies. Servers MAY implement side-effects of activities with these types.
Social API servers SHOULD support the MediaUpload endpoint. Social API servers SHOULD accept, store, and distribute common Web binary file formats, including images, audio, and video.
Social API servers SHOULD provide a proxyUrl endpoint.
[[rfc6749]] defines methods and protocols for granting access to resources. In the OAuth 2.0 Authorization Framework, ActivityPub social API servers act as a resource server. ActivityPub social API servers MAY designate a separate server as an authorization server, as defined by the OAuth 2.0 Authorization Framework, or act as their own authorization server.
Social API servers MUST support [[rfc6750]] to control access to ActivityPub objects, actors, and collections by actors with an id on the server.
Social API servers MAY use [[rfc9728]] to designate an authorization server. If such an external authorization server is not designated, Social API servers SHOULD act as their own authorization server.
Authorization servers SHOULD use [[rfc8414]] to provide authorization server metadata. The metadata SHOULD include:
authorization_endpointtoken_endpointscopes_supportedresponse_types_supportedgrant_types_supportedcode_challenge_methods_supportedtoken_endpoint_auth_methods_supportedclient_id_metadata_document_supported,
activitypub_object_id_as_client_id, or registration_endpoint
Social API servers MAY use ActivityPub actor endpoints to
declare the oauthAuthorizationEndpoint, oauthTokenEndpoint, and
oauthRegistrationEndpoint.
Authorization servers MUST support the authorization code grant.
Authorization servers SHOULD support the refresh token grant.
Authorization servers SHOULD support Client ID Metadata Document (CIMD) URLs as client ID. Authorization servers SHOULD declare support for CIMD in the authorization server metadata.
Authorization servers MAY support FEP-d8c2 URLs as client IDs. Authorization servers SHOULD declare support for FEP-d8c2 in the authorization server metadata and in the actor object.
Authorization servers MAY support [[rfc7591]] for dynamic client registration (DCR). Authorization servers that support DCR SHOULD declare the registration endpoint in the authorization server metadata and in the actor object.
Authorization servers MAY support the following scope identifiers.
| Scope identifier | Title | Meaning |
|---|---|---|
| https://swicg.github.io/activitypub-api/scopes#readall | Read all your data | Read any data for the user, including their profile, standard collections, content. |
| https://swicg.github.io/activitypub-api/scopes#readany | Read data on any server | Read data on the user's home server, however that is defined, and use proxyUrl to access data on other servers with the user's authorization. |
| https://swicg.github.io/activitypub-api/scopes#readown | Read data on its own server | Read data on the client's own server, with the same domain as the the client's CIMD identity. |
| https://swicg.github.io/activitypub-api/scopes#readlocal | Read data on your server | Read data on the user's home server, however that is defined. |
| https://swicg.github.io/activitypub-api/scopes#readinbox | Read your inbox feed | Read the actor's inbox collection and collection pages, and any activities in that collection, including activities from remote servers, and their properties, like actor and object. |
| https://swicg.github.io/activitypub-api/scopes#readoutbox | Read your outbox feed | Read the actor's outbox collection and collection pages, and any activities in that collection, and their properties, like actor and object. |
| https://swicg.github.io/activitypub-api/scopes#readfollowers | See who follows you | Read the actor's followers collection and collection pages, and any actors in that collection. |
| https://swicg.github.io/activitypub-api/scopes#readfollowing | See who you follow | Read the actor's following collection and collection pages, and any actors in that collection. |
| https://swicg.github.io/activitypub-api/scopes#readliked | See what you've liked | Read the actor's liked collection and collection pages, and any objects in that collection. |
| https://swicg.github.io/activitypub-api/scopes#createcontent | Create new content | Make new notes, articles, images, videos, or audio. |
| https://swicg.github.io/activitypub-api/scopes#updatecontent | Edit existing content | Update existing notes, articles, images, videos, or audio, whether or not they were created with the same client. |
| https://swicg.github.io/activitypub-api/scopes#deletecontent | Delete content | Delete existing notes, articles, images, videos, or audio, whether or not they were created with the same client. |
| https://swicg.github.io/activitypub-api/scopes#follow | Follow and unfollow accounts | Follow local and remote accounts. Unfollow local and remote accounts. |
| https://swicg.github.io/activitypub-api/scopes#managefollowers | Accept, reject, and remove followers | Accept and reject local and remote follow requests. Remove local and remote followers. |
| https://swicg.github.io/activitypub-api/scopes#managecollections | Add items to and remove items from collections | For user-managed collections, add and remove items. |
| https://swicg.github.io/activitypub-api/scopes#like | Like and unlike content | Like notes, articles, video, audio, images, and other content. Undo those likes. |
| https://swicg.github.io/activitypub-api/scopes#share | Share and unshare content | Announce notes, articles, video, audio, images, and other content. Announce any activities. Undo those announcements. |
| https://swicg.github.io/activitypub-api/scopes#block | Block and unblock accounts | Block local and remote actors. Undo those blocks. |
| https://swicg.github.io/activitypub-api/scopes#flag | Report accounts | Flag local and remote accounts to the user's moderators and/or the accounts' moderators. |
| https://swicg.github.io/activitypub-api/scopes#reactlocal | Interact with content on your server | Like, announce, and reply to notes, articles, video, audio and images and other content on the actor's own server. |
| https://swicg.github.io/activitypub-api/scopes#reactany | Interact with content on any server | Like, announce, and reply to notes, articles, video, audio and images and other content on the actor's own server or remote servers. |
| https://swicg.github.io/activitypub-api/scopes#reactown | Interact with content on its own server | Like, announce, and reply to notes, articles, video, audio and images and other content on the same server as the CIMD identity of the client. |
| https://swicg.github.io/activitypub-api/scopes#addressall | Post to anyone | The client can include any addressee in the to, cc, bcc, bto or audience properties of a new activity. |
| https://swicg.github.io/activitypub-api/scopes#addresspublic | Post publicly | The client can include as:Public in the to, cc, bcc, bto or audience properties of a new activity. |
| https://swicg.github.io/activitypub-api/scopes#addressactor | Post privately | The client can include other actor's ids in the to, cc, bcc, bto or audience properties of a new activity. |
| https://swicg.github.io/activitypub-api/scopes#addressfollowers | Post to your followers | The client can include the actor's followers collection in the to, cc, bcc, bto or audience properties of a new activity. |
| https://swicg.github.io/activitypub-api/scopes#uploadfiles | Upload files | The client can use the MediaUpload endpoint. |
| https://swicg.github.io/activitypub-api/scopes#updateprofile | Change your profile, including your avatar | The client can update the actor's profile, adding or removing any properties in the profile, including the icon property. |
Authorization servers SHOULD support [[rfc7636]] (PKCE) for
public clients. Authorization servers that support PKCE SHOULD
support the S256 challenge method, and SHOULD declare
support for the S256 challenge method in the authorization server
metadata.
The authorization server MUST provide the ActivityPub actor id of the authenticated user to the client.
The authorization server SHOULD include an
activitypub_actor_id property in the token endpoint
results. This is the https: URL for the ActivityPub actor ID.
The authorization server MAY use [[rfc7519]] for the
access_token. If so, it MUST use the ActivityPub actor
ID as the sub claim.
The authorization server MAY support OpenID
Connect. If so, it MUST use the ActivityPub actor ID as the
sub claim in the UserInfo endpoint.
This profile adds requirements and restrictions to the HTTP interactions of the social API server.
Social API servers SHOULD use [[rfc9457]] to indicate problems or successful HTTP status details.
Social API servers MAY use FEP-c180 to provide ActivityPub-specific problem details.
Social API servers SHOULD support [[CORS]], including CORS pre-flight requests.
Social API servers SHOULD allow access to all origins ('*') with the Access-Control-Allow-Origin header.
Social API servers SHOULD support [[rfc9111]] for HTTP caching.
Social API servers MAY limit API requests by any conditions necessary. Servers MAY have different rate limiting policies for different types of requests, including but not limited to different HTTP methods, different types of ActivityPub object, different ActivityPub collections, network conditions, time of day, calendar date, different API clients, or different users.
Social API servers SHOULD support rate limits appropriate for interactive use of the server under typical social network workloads. Social API servers SHOULD support different rate limits for sustained rate (average number of requests over minutes or hours) and burst rate (a high number of requests in a few seconds, as when loading or scrolling an inbox or followers collection).
Social API servers MUST use the 429 Too Many Requests HTTP status code to indicate that the client has reached its rate limit. Social API servers SHOULD include the Retry-After header in the HTTP response to indicate how long the client should wait.
Social API servers SHOULD use the RateLimit header fields for HTTP to indicate rate limit policies, remaining request quotas, and quota reset times.