Update user role

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

Change a user's role within their organisation. The roles are owner, admin, member and viewer.

One safety check applies: an organisation must always retain at least one owner. Demoting the sole owner is refused with LAST_OWNER.

Returns 404 if the user has no organisation membership.

Records a USER_ROLE_CHANGED action in the audit log, capturing the previous and new role.

Error responses:

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

Path parameters

idstringrequired

User ID.

Body parameters

rolestringrequired

New organisation role.

owneradminmemberviewer

Response

200Role changed. Returns previous and new role.

Show response fields

messagestring

Error codes

400Cannot demote the last owner.

404User has no organisation membership.

RequestPATCH/v1/admin/users/{id}/rolecurl

curl -X PATCH https://api.speybooks.com/v1/admin/users/12/role \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Response200

{
  "success": true,
  "data": {
    "message": "Role changed from member to admin"
  }
}