Skip to content

Remove one sharing grant from a collection

DELETE
/collections/{id}/acls/{principal_type}/{principal_id}/{permission}

Removes one grant from a collection: the one with exactly this principal type, principal id and level. Other grants, including other levels for the same user, stay.

You need to be signed in. The collection’s owner and holders of collections.admin or system.admin granted globally can remove grants. 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. When no grant matches exactly, the answer is 404, including on a second request.

The path values are matched as stored rather than checked, so an expired grant or an old role or team grant can be removed this way, and a user ref must be written as it was stored: 1 doesn’t remove a grant stored as 001.

Removing a grant takes away only what that grant gave. The user can still read the collection if it’s public or through another grant that hasn’t expired. They aren’t notified, and no activity or audit entry is recorded.

id
required
string format: uuid

The collection’s id.

principal_type
required
string
Allowed values: user role team

The principal type of the grant to remove, as listed.

principal_id
required
string
<= 64 characters

The principal id of the grant to remove, exactly as listed.

permission
required
string
Allowed values: read write admin

The level of the grant to remove, as listed.

The grant was removed.

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