Skip to content

List a user's capability overrides

GET
/admin/users/{ref}/capabilities

Lists the grants and revokes recorded directly on a user, whether they apply across the instance or within a team. Capabilities the user gets from roles aren’t included.

Needs the users.read capability. An unknown user gets 404.

ref
required
integer format: int64

The user’s grants and revokes.

A grant adds a capability to what the user’s roles give them. A revoke takes one away at the same scope, even when a role gives it. Each list is sorted by capability code; for the same code, the instance-wide entry comes first.

object
grants
required
Array<object>

One grant or revoke. team_id is the team it applies to; it’s left out when the entry applies across the instance. For a revoke, granted_by and granted_at say who revoked it and when.

object
capability
required
string
team_id
string format: uuid
nullable
note

The reason given for it. Left out when none was given.

string
granted_by

The ref of the user who added it. Left out when that wasn’t recorded.

integer format: int64
nullable
granted_at
required
string format: date-time
expires_at

When it expires. Left out for a permanent entry. An hourly cleanup job removes expired entries, and cached permissions can take longer to update, so it can keep applying for a while after this time. An expired instance-wide system.admin grant can stay in effect if the cleanup job finds that removing it would leave no system administrator.

string format: date-time
nullable
revokes
required
Array<object>

One grant or revoke. team_id is the team it applies to; it’s left out when the entry applies across the instance. For a revoke, granted_by and granted_at say who revoked it and when.

object
capability
required
string
team_id
string format: uuid
nullable
note

The reason given for it. Left out when none was given.

string
granted_by

The ref of the user who added it. Left out when that wasn’t recorded.

integer format: int64
nullable
granted_at
required
string format: date-time
expires_at

When it expires. Left out for a permanent entry. An hourly cleanup job removes expired entries, and cached permissions can take longer to update, so it can keep applying for a while after this time. An expired instance-wide system.admin grant can stay in effect if the cleanup job finds that removing it would leave no system administrator.

string format: date-time
nullable

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