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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Request Body required
Section titled “Request Body required ”object
Responses
Section titled “ Responses ”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
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed