List federation shares
GET /admin/federation/shares
Lists the shares granted from your instance to paired peers, by object, by peer or by the user who granted them.
Give one filter: an object (object_kind with object_id), a peer
(peer_id) or a granting user (grantor_user_ref). If you send
more than one, the first complete one in that order is used and the
others are ignored; object_kind or object_id on its own doesn’t
count. With no filter you get 400.
Revoked shares are left out, but expired ones aren’t: a share whose
expires_at has passed stays listed until the expiry job revokes
it, which it does when the app starts and then every hour. An object
filter shows only shares of that exact object, not shares of a
collection that contains it.
Shares come newest first; with a peer filter they’re grouped by
object kind first. limit (100 by default) applies to the peer and
grantor filters, and the object filter returns every match. There’s
no paging.
You need federation.read or system.admin. You don’t have to be
the user who granted the shares.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Responses
Section titled “ Responses ”Unrevoked shares matching the filter.
object
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 completed