Grant a permission on a collection to a principal
POST /collections/{id}/acls
Inserts one ACL row. Requires write access to the collection (owner / collections.admin / system.admin).
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
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.
Responses
Section titled “ Responses ”ACL row added
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 completedResource not found
object
Human-readable error summary
Example
the request could not be completed