Ask for access to an asset
POST /assets/{id}/request-access
Files a request about an asset. It’s listed in the pending queue at
GET /admin/requests, and if the asset exists and isn’t deleted,
its owner also sees it in GET /account/requests/incoming.
Leave out capability, as the web app does, and the request names
content.access.request. Approving that records that your request
was accepted; it doesn’t unlock the asset, because nothing can yet
grant access to a single item. Name any other capability instead and
an approval grants it to you across the whole instance; only holders
of share.grant or system.admin can decide those.
The asset isn’t checked: any id is accepted, whether or not the
asset exists, is visible to you, or is already yours. An unknown
capability gets a 400, and so does content.restore.request; to ask
for a deleted item back, use POST /account/trash/{kind}/{id}/request-restore.
If you already have the same request pending, you get 200 with it
unchanged, and a new reason isn’t saved. Otherwise you get 201.
Once a request has been decided you can ask again. Your reason is
shown to whoever reviews the request and kept in the audit log. The
asset’s owner and the approvers are notified without it;
notifications and the audit entry are best effort.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
What you’re asking for. Leave it out to ask about this asset with
content.access.request, which unlocks nothing on its own.
Any other capability code is a request for that capability across
the whole instance. The asset’s owner can’t decide it; only holders
of share.grant or system.admin can.
Why you’re asking. Optional. Whoever reviews the request sees it, and it’s kept in the audit log.
Responses
Section titled “ Responses ”You already had this request pending. It’s returned unchanged, and nobody is notified again.
A request and where it stands.
object
What target_id refers to. Access requests are always for an
asset; a restoration request can name an asset, post or
collection.
The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.
What the request is for, which also decides who can answer it:
content.access.request: a request to see an asset. The asset’s owner can decide it, as can holders ofshare.grantorsystem.admin. Granting it unlocks nothing.content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder ofsystem.admin, can decide it. Granting it restores the item and grants no capability.- Any other code: a request for that capability across the whole
instance. Only holders of
share.grantorsystem.admincan decide it, and granting it gives the requester that capability.
On the two queues, whether you can decide this request, checked when the list was built. It can change before you act, and the decide call checks again. Left out on other responses.
The requester’s reason, if they gave one.
pending until someone decides it, then granted or denied. When the periodic cleanup removes an expired grant, the server tries to mark its request expired; a request can stay granted if that doesn’t happen. Pending requests don’t expire.
The reason recorded with the decision, if any. When a restoration request is granted for an item that was already back, a note says so here.
The expiry given when the request was granted; left out when there
was none. It describes the grant made at that time: approving a
later request for the same capability replaces that instance-wide
grant and its link to this request, so a request can show granted
after its grant has changed or gone.
Request filed.
A request and where it stands.
object
What target_id refers to. Access requests are always for an
asset; a restoration request can name an asset, post or
collection.
The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.
What the request is for, which also decides who can answer it:
content.access.request: a request to see an asset. The asset’s owner can decide it, as can holders ofshare.grantorsystem.admin. Granting it unlocks nothing.content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder ofsystem.admin, can decide it. Granting it restores the item and grants no capability.- Any other code: a request for that capability across the whole
instance. Only holders of
share.grantorsystem.admincan decide it, and granting it gives the requester that capability.
On the two queues, whether you can decide this request, checked when the list was built. It can change before you act, and the decide call checks again. Left out on other responses.
The requester’s reason, if they gave one.
pending until someone decides it, then granted or denied. When the periodic cleanup removes an expired grant, the server tries to mark its request expired; a request can stay granted if that doesn’t happen. Pending requests don’t expire.
The reason recorded with the decision, if any. When a restoration request is granted for an item that was already back, a note says so here.
The expiry given when the request was granted; left out when there
was none. It describes the grant made at that time: approving a
later request for the same capability replaces that instance-wide
grant and its link to this request, so a request can show granted
after its grant has changed or gone.
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"}