Skip to content

Revoke a federation share

DELETE
/admin/federation/shares/{id}

Ends a share. The share is kept with revoked_at set, and an aa:Unshare activity and a federation.share.revoked audit event are saved with it in one transaction.

Only the user who granted the share, or someone with system.admin, can revoke it; owning the object isn’t enough. A share that has expired but isn’t revoked yet can still be revoked. One that’s already revoked, by a user or by the expiry job, returns 409 with the share.

Once remote instances act on shares, the recipient is expected to purge its cached copy and keep its own derivative work (comments, annotations). Remote instances do not act on shares yet.

Like any activity about the object, the aa:Unshare reaches the outbox only for a post with explicit-share visibility, and goes to the peers that still hold a share of it, so the peer you revoked normally isn’t sent it. As shipped, the outbox keeps each post’s recipients in memory and doesn’t update them when shares change, so until the app restarts, activity about the post can keep going to the revoked peer.

id
required
string format: uuid

Revoked.

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Share already revoked.

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