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.
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 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 Social API 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
Authorization servers MAY use ActivityPub actor endpoints to
declare the oauthAuthorizationEndpoint, oauthTokenEndpoint, and
oauthRegistrationEndpoint.
Authorization servers MUST support the authorization code grant.
Authorization Social API servers SHOULD support the refresh token grant.
Authorization Social API servers SHOULD support Client ID Metadata Document (CIMD) URLs as client ID. Authorization Social API servers SHOULD declare support for CIMD in the authorization server metadata.
Authorization servers MAY support FEP-d8c2 URLs as client IDs. Authorization Social API 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.
activitypub:read:all - read any data on this or
other serversactivitypub:read:local:all - read any data on this
serveractivitypub:read:remote:all - read any data on
remote server (using proxyUrl)activitypub:read:me:all - read any local or remote
data on this or other servers with the user as owner (actor,
attributedTo)activitypub:read:me:actor - read actor
profileactivitypub:read:me:inbox - Client can read the
user inbox, any activity in the inbox, and any properties of those
activitiesactivitypub:read:me:outbox - Client can read the
user outbox, any activity in the outbox, and any properties of
those activitiesactivitypub:read:me:following - Client can read
the user following, any actor in the following, and any properties
of those actorsactivitypub:read:me:followers - Client can read
the user followers, any actor in the followers, and any properties
of those actorsactivitypub:read:me:liked - Client can read the
user liked, any object in the liked, and any properties of those
objectsactivitypub:write:all - generate any activity by
posting to the user outboxactivitypub:write:create - generate a Create
activityactivitypub:write:update - generate an Update
activityactivitypub:write:delete - generate a Delete
activityactivitypub:write:follow - generate a Follow
activityactivitypub:write:accept - generate an Accept
activityactivitypub:write:reject - generate a Reject
activityactivitypub:write:add - generate an Add
activityactivitypub:write:remove - generate a Remove
activityactivitypub:write:like - generate a Like
activityactivitypub:write:block - generate a Block
activityactivitypub:write:question - generate a Question
activityactivitypub:write:flag - generate a Flag
activityactivitypub:write:announce - generate an Announce
activityactivitypub:write:undo:all - generate any Undo
activityactivitypub:write:undo:like - generate an Undo
activity with a Like activity as the objectactivitypub:write:undo:follow - generate an Undo
activity with a Follow activity as the objectactivitypub:write:undo:block - generate an Undo
activity with a Block activity as the objectactivitypub:write:undo:announce - generate an Undo
activity with an Announce activity as the objectactivitypub:write:all:sameorigin - generate any
activity with the object, target, or origin property in the same
origin as the client IDactivitypub:write:create:sameorigin - generate a
Create activity with the object in the same origin as the client
IDactivitypub:write:update:sameorigin - generate an
Update activity with the object in the same origin as the client
IDactivitypub:write:delete:sameorigin - generate a
Delete activity with the object in the same origin as the client
IDactivitypub:write:follow:sameorigin - generate a
Follow activity with the object in the same origin as the client
IDactivitypub:write:add:sameorigin - generate an Add
activity with the object or target in the same origin as the client
IDactivitypub:write:remove:sameorigin - generate a
Remove activity with the object or target in the same origin as the
client IDactivitypub:write:like:sameorigin - generate a
Like activity with the object in the same origin as the client
IDactivitypub:write:block:sameorigin - generate a
Block activity with the object in the same origin as the client
IDactivitypub:write:announce:sameorigin - generate
an Announce activity with the object in the same origin as the
client IDactivitypub:write:flag:sameorigin - generate a
Flag activity with the object in the same origin as the client
IDactivitypub:write:undo:all:sameorigin - generate
an Undo activity with an object as an activity of any type with the
object, target or origin in the same origin as the client IDactivitypub:write:undo:like:sameorigin - generate
an Undo activity with a Like activity as the object with the object
property in the same origin as the client IDactivitypub:write:undo:follow:sameorigin -
generate an Undo activity with a Follow activity as the object with
the object property in the same origin as the client IDactivitypub:write:undo:block:sameorigin - generate
an Undo activity with a Block activity as the object with the
object property in the same origin as the client IDactivitypub:write:undo:announce:sameorigin -
generate Undo activity with an Announce activity as the object with
the object in the same origin as the client IDactivitypub:write:create:inreplyto:sameorigin -
generate a Create activity with the object inReplyTo an object in
the same origin as the client IDactivitypub:write:update:inreplyto:sameorigin -
generate a Delete activity with the object inReplyTo an object in
the same origin as the client IDactivitypub:write:delete:inreplyto:sameorigin -
generate a Delete activity with the object inReplyTo an object in
the same origin as the client IDread - a synonym for
activitypub:read:all
write - a synonym for
activitypub:write:all
write:sameorigin - a synonym for
activitypub:write:all:sameorigin
Authorization Social API 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.