Share a collection with a user
POST /collections/{id}/acls
Shares a collection with one user by storing a grant on it. While the grant hasn’t expired, that user can read the collection whatever its visibility.
You need to be signed in. The collection’s owner and holders of
collections.admin or system.admin granted globally can share it.
Others get 403. The collection is looked up through each server’s
cached copy of its details, so one that doesn’t exist answers 404,
and a deleted one does too unless the server still holds an
out-of-date copy. A body that isn’t valid JSON is refused with 400
before any of these checks.
principal_type must be user: role and team are refused with
400 because they give no access on collections. principal_id is
the user’s numeric ref in plain digits; zero, a negative or
non-numeric value is refused with 400. The account isn’t looked up,
and a ref written with leading zeros or a plus sign is accepted but
stored as written, so it gives no access.
read, write and admin all give the same thing here: the right
to read the collection, which means opening it, seeing it among
collections shared with them and listing its posts, each of which
still follows its own rules. None of them lets the user edit the
collection, change its posts or manage its grants. An unknown or
missing permission isn’t refused with 400; the database rejects it
and the answer is 500. Without expires_at the grant doesn’t
expire. A time that has already passed is accepted and stored, but
the grant gives no access.
Each user and level is one grant. Sending the same user and level
again replaces its expiry (leaving expires_at out makes it
permanent) and records you and the current time as its latest grant;
a different level is a separate grant. When two requests change the
same grant at once, the one saved last stands. The user isn’t
notified, and no activity or audit entry is recorded.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The collection’s id.
Request Body required
Section titled “Request Body required ”object
Who the grant is for, by reference rather than name: for user, the
account’s numeric ref in plain digits; for role or team, its
UUID in lowercase.
The value is stored exactly as sent and compared as written, so a ref with leading zeros or a plus sign is accepted but matches no one. Each route’s description says which principal types it accepts.
When the grant should stop giving access. Leave it out or send null for a grant that doesn’t expire. A time that has already passed is accepted, but the grant gives no access.
Responses
Section titled “ Responses ”The grant was saved, or an existing grant for the same user and level was updated.
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