Skip to content

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.

id
required
string format: uuid

The collection’s id.

object
principal_type
required
string
Allowed values: user role team
principal_id
required

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.

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

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.

string format: date-time
nullable

The grant was saved, or an existing grant for the same user and level was updated.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

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

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed