Share an object with a peer
POST /admin/federation/shares
Shares a post, asset or collection on your instance with a paired peer, or with one user on that peer. The share is recorded locally and the object itself isn’t sent.
You can share objects you own; with system.admin you can share any
object, and the server doesn’t check that it exists. The share is in
your name either way, which decides who can revoke it. The peer must
be enabled and connected.
The share, an aa:Share activity and a federation.share.granted
audit event are saved in one transaction. The activity reaches the
outbox only when the object is a post with explicit-share
visibility, and is then queued for the peers that post is shared
with (see GET /admin/federation/outbox). As shipped, the outbox
keeps each post’s recipients in memory and doesn’t update them when
shares change, so a new share may not reach the outbox until the app
restarts.
Remote instances do not act on shares yet: today only likes and comments take effect between paired instances (see the ArchivePub overview, “What works today”).
You can’t grant the same object to the same peer and user twice while your earlier share is unrevoked, even if it has expired: you get 409. The 409 body shows an unexpired share of this object for that peer, but it may not be yours or the one that caused the conflict: it can be someone else’s share, including their notes. If the server finds none, for example because your share has expired, every field is empty or zero.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
The kind of object to share. Ownership is checked only for post,
asset and collection, so the other kinds can be shared only by
an admin.
The actor URL of one user on the peer, to share with only that user. Leave it out, or send an empty string, to share with the whole peer. It’s optional for every object, including restricted and embargoed ones. Only deliveries to a named user can be encrypted, and only if the peer supports encryption and that user’s key is known.
How much the peer may do with the object, from view up to remix. It’s stored with the share; remote instances don’t act on it yet.
When the share should end. The expiry job revokes it after that time, checking when the app starts and then every hour. Leave it out for a share that doesn’t expire.
A note about the share for your admins. As shipped, it’s also copied into the aa:Share activity, so it reaches the peer if that activity is delivered. Don’t put anything here you wouldn’t show the peer.
Responses
Section titled “ Responses ”The saved share.
One share: an object on your instance shared with a paired peer, or with one user on it. Pairing alone shares nothing; each share covers one object. Remote instances don’t act on shares yet.
object
The user who granted the share. Only they, or someone with system.admin, can revoke it.
The one user on the peer this share is for. Left out when it’s for the whole peer.
When the share is set to end. It stays unrevoked after this until the expiry job revokes it.
The aa:Share activity recorded with the grant.
When the share was revoked, by a user or by the expiry job. Left out until then.
The aa:Unshare activity recorded when it was revoked.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedNo peer with that peer_id.
object
Human-readable error summary
Example
the request could not be completedYou already have an unrevoked share of this object for this peer and user.
One share: an object on your instance shared with a paired peer, or with one user on it. Pairing alone shares nothing; each share covers one object. Remote instances don’t act on shares yet.
object
The user who granted the share. Only they, or someone with system.admin, can revoke it.
The one user on the peer this share is for. Left out when it’s for the whole peer.
When the share is set to end. It stays unrevoked after this until the expiry job revokes it.
The aa:Share activity recorded with the grant.
When the share was revoked, by a user or by the expiry job. Left out until then.
The aa:Unshare activity recorded when it was revoked.