Skip to content

Set a user's role

PUT
/auth/users/{ref}/role

Sets the user’s global role, replacing all of their current global roles. Roles they hold within a team are kept. Needs the users.write capability. An unknown role_id gets 404.

If the user already holds the new role globally, the outcome isn’t guaranteed: the call deletes and updates that same assignment in one database statement, which PostgreSQL doesn’t support.

If the new role doesn’t include system.admin and this user is the only system administrator, the change is refused with 400. Grant system.admin to someone else first.

ref
required
integer format: int64
object
role_id
required
string format: uuid

The role was set.

The new role doesn’t include system.admin and this user is the only system administrator, so the change was refused. 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