Skip to content

Revoke a capability from a user

POST
/admin/users/{ref}/revokes

Takes a capability away from a user, across the instance or, with team_id, for one team. A revoke wins over the user’s roles and grants at the same scope. A revoke for a team only cancels what was given for that exact team, so a capability given for a parent team still reaches it.

Revoking the same capability for the same scope again updates the existing revoke: its note and expiry are replaced with the new values, so leaving them out clears them. Needs the users.write capability. An unknown user gets 404. An instance-wide system.admin revoke is refused with 400 when this user is the only system administrator.

ref
required
integer format: int64

Set team_id to limit the override to a team; leave it out, or send null, for one that applies across the instance.

object
capability
required

The capability code, such as users.write.

string
team_id
string format: uuid
nullable
note

A reason to record with it.

string
<= 500 characters
expires_at

When it should expire. It must be in the future, or you get 400. Leave it out for a permanent one.

string format: date-time
nullable

The revoke was added or updated.

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