Skip to content

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 of share.grant or system.admin. Granting records agreement and unlocks nothing.
  • content.restore.request: only whoever deleted the item, or a holder of system.admin, can decide. Owning the item or holding share.grant isn’t enough. Granting restores the item and grants no capability.
  • Any other capability: only holders of share.grant or system.admin can 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.

id
required
string format: uuid
object
decision
required
string
Allowed values: granted denied
reason

Why you decided this way. The requester sees it, and it’s kept in the audit log.

string
<= 1000 characters
expires_at

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.

string format: date-time
nullable

Decided. The response is the updated request.

A request and where it stands.

object
id
required
string format: uuid
requester_user_ref
required
integer format: int64
target_kind
required

What target_id refers to. Access requests are always for an asset; a restoration request can name an asset, post or collection.

string
Allowed values: asset post collection
target_id
required

The id of the item the request is about. It isn’t checked when an access request is filed, so it may not exist.

string format: uuid
requested_capability
required

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 of share.grant or system.admin. Granting it unlocks nothing.
  • content.restore.request: a request to get a deleted item back. Only whoever deleted the item, or a holder of system.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.grant or system.admin can decide it, and granting it gives the requester that capability.
string
decidable_by_caller

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.

boolean
reason

The requester’s reason, if they gave one.

string
state
required

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.

string
Allowed values: pending granted denied expired
decided_at
string format: date-time
nullable
decided_by_user_ref
integer format: int64
nullable
decision_reason

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.

string
expires_at

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.

string format: date-time
nullable
requested_at
required
string format: date-time

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

The request was already decided, or the item a restoration request asks for has been permanently deleted.

object
error
required

Human-readable error summary

string
Example
the request could not be completed