Grant a permission on an asset_type to a principal
POST /asset_types/{ref}/acls
Inserts one ACL row. Re-granting the same tuple refreshes granted_at / granted_by / expires_at — idempotent. The first row inserted flips the type from “open” to “restricted” for non-admin callers.
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