Grant a permission on a post to a principal

POST

/posts/{id}/acls

• Local development behind nginx (port 8088 by default)

Inserts one ACL row. The same principal can hold multiple permission levels (e.g. read AND write) — that’s two POSTs. Requires write access to the post (owner / posts.admin / system.admin) so a contributor can’t grant access beyond their own ability to mutate.

A user grant also emits a post_shared_with_me notification to the grantee (#875), so a share is not silent. role and team grants name no single recipient and notify nobody. Notification delivery is best-effort and runs after the row is written: the grant stands whether or not the notification does.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body ^required

object

principal_type

required

string

Allowed values: user role team

principal_id

required

A REFERENCE, not a name. BIGINT user.ref when principal_type=user; the row’s UUID when it is role or team.

The pattern admits the union of both forms because one schema serves all three principal types; the handler enforces the type-specific half and rejects a mismatch with 400. Passing a username here used to be accepted and stored, producing a grant that no read rule could ever match (#916).

Which principal types actually CONFER access depends on the surface. asset_type_acls honours all three. post_acls and collection_acls honour user only — their read rules gate on principal_type = 'user' because role/team scoping on content is ADR 0010 Layer 5 and unimplemented — so those two endpoints reject role and team with 400 rather than storing a grant that does nothing.

string

<= 64 characters /^([0-9]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/

permission

required

string

Allowed values: read write admin

expires_at

string format: date-time

nullable

Responses

204

ACL row added

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

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed