Decide a request
POST /admin/requests/{id}/decide
Grants or denies a pending request. Who may decide it, and what
granting does, depends on its requested_capability.
content.access.request: the asset’s owner can decide, as can holders ofshare.grantorsystem.admin. Granting records agreement and unlocks nothing.content.restore.request: only whoever deleted the item, or a holder ofsystem.admin, can decide. Owning the item or holdingshare.grantisn’t enough. Granting restores the item and grants no capability.- Any other capability: only holders of
share.grantorsystem.admincan decide. Granting gives the requester that capability across the whole instance, and replaces their existing instance-wide grant of it, if any, expiry included.
A new capability may not apply straight away: this call doesn’t
refresh the requester’s cached permissions. expires_at sets when a
granted capability expires; leave it out for no expiry. Expired
grants are removed by a cleanup that normally runs hourly, and
cached permissions can take longer to catch up, so a grant can keep
working for a while after it expires. An expired instance-wide
system.admin grant can stay in effect if removing it would leave
no system administrator.
For a restoration request the item is restored first, and the request is marked granted afterwards in a separate step. If marking it fails, the item stays restored and the request can still be pending or show a decision someone else made in the meantime, granted or denied. If the item was already restored the grant still succeeds and the decision reason says so; if it has been permanently deleted you get 409.
Denying records the decision and doesn’t remove any access the
requester already has. A request that’s already decided gets 409. An
unknown request id gets 404 if you hold share.grant or
system.admin, and 403 otherwise, the same as a request you can’t
decide. The requester is notified of the decision with your reason,
and it’s recorded in the audit log, both on a best-effort basis.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
Why you decided this way. The requester sees it, and it’s kept in the audit log.
When a granted capability should expire. Leave it out or send null
for no expiry. A time in the past gets a 400, even when denying. A
future time is ignored when denying, and granting a restoration
request with one gets a 400.
Responses
Section titled “ Responses ”Decided. The response is the updated request.
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"}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 completedThe request was already decided, or the item a restoration request asks for has been permanently deleted.
object
Human-readable error summary
Example
the request could not be completed