Grant a federation share (write-ahead audit)

POST

/admin/federation/shares

• Local development behind nginx (port 8088 by default)

Creates federation_shares row + emits aa:Share activity + writes federation.share.granted audit event — all in one transaction per the design proposal §7.2 write-ahead invariant. Idempotent: duplicate POST on the active-row tuple (grantor, object, peer, target_user) returns 409 with the existing share.

Permission: caller must own the object OR have system.admin. Restricted objects require target_user_url (NaCl envelope wrap needs a key).

Authorizations

• cookieAuth
• bearerAuth

Request Body ^required

object

object_kind

required

‘user’ is excluded from the operator-facing API — user/follower shares are server-internal (Accept(Follow) creates them).

string

Allowed values: asset post collection workspace brand_kit

object_id

required

string format: uuid

peer_id

required

string format: uuid

target_user_url

Recipient’s actor URL on the peer. Omit for a broadcast share (any user on the peer). REQUIRED for restricted/embargo objects (server validates).

string

scope

required

string

Allowed values: view comment annotate remix

expires_at

string format: date-time

nullable

notes

string

<= 2000 characters

Responses

201

Share granted.

One federation_shares row per the 1.22.C design proposal. Pairing alone shares nothing; each row here is an explicit per-object grant.

object

id

required

string format: uuid

grantor_user_ref

required

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

NULL = broadcast within peer; non-null = specific user actor URL

string

nullable

scope

required

string

Allowed values: view comment annotate remix

expires_at

string format: date-time

nullable

notes

required

string

granted_activity_id

required

string format: uuid

granted_at

required

string format: date-time

revoked_at

string format: date-time

nullable

revoked_activity_id

string format: uuid

nullable

created_at

required

string format: date-time

updated_at

required

string format: date-time

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Object or peer not found.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

409

Active share already exists for this tuple.

One federation_shares row per the 1.22.C design proposal. Pairing alone shares nothing; each row here is an explicit per-object grant.

object

id

required

string format: uuid

grantor_user_ref

required

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

NULL = broadcast within peer; non-null = specific user actor URL

string

nullable

scope

required

string

Allowed values: view comment annotate remix

expires_at

string format: date-time

nullable

notes

required

string

granted_activity_id

required

string format: uuid

granted_at

required

string format: date-time

revoked_at

string format: date-time

nullable

revoked_activity_id

string format: uuid

nullable

created_at

required

string format: date-time

updated_at

required

string format: date-time