Skip to content

Remove a capability grant from a user

DELETE
/admin/users/{ref}/grants/{capability}

Removes one of a user’s grants. Grants have no ID: name the capability in the path, and add team_id to remove the grant for that team instead of the instance-wide one. The user keeps the capability if a role still gives it. Needs the users.write capability. If there’s no matching grant, you get 404.

Removing an instance-wide system.admin grant is refused with 400 when this user is the only system administrator.

ref
required
integer format: int64
capability
required
string
team_id
string format: uuid

Grant removed.

This user is the only system administrator, so their instance-wide system.admin grant can’t be removed. Grant system.admin to another user first.

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