Skip to content

Grant a capability to a user

POST
/admin/users/{ref}/grants

Grants a capability to a user, across the instance or, with team_id, within that team and the teams below it. Use a code from GET /auth/capabilities.

Granting the same capability for the same scope again updates the existing grant: 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.

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 grant 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