Share a post with a user
POST /posts/{id}/acls
Shares a post with one user by storing a grant on it. While the
grant hasn’t expired, that user can read the post whatever its
visibility, and its pictures keep their own access rules. Sharing
doesn’t publish a draft: while the post is a draft, a grant can let
in only a holder of posts.admin or system.admin granted
globally, and other users can read it once it’s published.
You need to be signed in. Only the post’s author and holders of
posts.admin or system.admin granted globally can share it;
holding posts.admin only for the post’s team lets you list and
remove grants but not add them (403). A post that doesn’t exist or
is deleted is 404. 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 posts. principal_id is the
user’s numeric ref in plain digits; a username, 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 post. None of them lets the user edit the post 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.
After the grant is saved, and again on each repeat, the server tries to send the user an in-app notification. None is sent when you share with yourself, when either of you has blocked the other, or when their settings don’t include in-app notices for shares, and a failure is only logged. The grant stands either way, and share notifications aren’t sent by email.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’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