Update user role

PATCH https://app.speybooks.com/api/v1/admin/users/{id}/role

Change a user's role within their organisation. Available roles: owner, admin, member, viewer.

Safety Check

If demoting the current owner, the endpoint checks that at least one other owner exists. Returns 400 with LAST_OWNER if the user is the sole owner being demoted.

Returns 404 if the user has no organisation membership.

Side Effects

  • Writes USER_ROLE_CHANGED to admin_audit_log with previous and new role

Error responses:

  • 400 { code: "LAST_OWNER" } — cannot demote the sole owner
  • 404 { code: "NOT_FOUND" } — no org membership found

Path parameters

id string required
User ID.

Body parameters

role string required
New organisation role.
owneradminmemberviewer

Response

200 Role changed. Returns previous and new role.
Show response fields
message string

Error codes

400 Cannot demote the last owner.
404 User has no organisation membership.