Skip to content

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.

object_kind
string
Allowed values: asset post collection workspace brand_kit user
object_id
string format: uuid
peer_id
string format: uuid
grantor_user_ref
integer format: int64
limit
integer
default: 100 >= 1 <= 500

Unrevoked shares matching the filter.

object
items
required
Array<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
id
required
string format: uuid
grantor_user_ref
required

The user who granted the share. Only they, or someone with system.admin, can revoke it.

integer format: int64
object_kind
required
string
Allowed values: asset post collection workspace brand_kit user
object_id
required
string format: uuid
peer_id
required
string format: uuid
target_user_url

The one user on the peer this share is for. Left out when it’s for the whole peer.

string
nullable
scope
required
string
Allowed values: view comment annotate remix
expires_at

When the share is set to end. It stays unrevoked after this until the expiry job revokes it.

string format: date-time
nullable
notes
required
string
granted_activity_id
required

The aa:Share activity recorded with the grant.

string format: uuid
granted_at
required
string format: date-time
revoked_at

When the share was revoked, by a user or by the expiry job. Left out until then.

string format: date-time
nullable
revoked_activity_id

The aa:Unshare activity recorded when it was revoked.

string format: uuid
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed