update_team_member_role
Move an existing collaborator onto a different role within the team.
Moves an existing collaborator onto a different role. This is the only way to re-role someone without removing and re-inviting them — the dashboard's team settings page offers invite, remove and cancel-invitation only, so there is no UI equivalent.
The team owner cannot be re-roled: ownership is not a membership row and carries everything unconditionally.
Growth-tier capability. On a lower tier this returns TEAM_TIER_REQUIRED and
changes nothing.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
team_id*stringUUID of the team.
user_id*stringUUID of the collaborator whose role is changing.
role*stringRole code to move them onto. Must already exist on the team.
What it returns
{ "data": { "team_id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86", "user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80", "role": "manager" }}Emits team.member.role_changed.
This is what makes that event reachable
Nothing in Subscriby called the underlying re-role path before this shipped,
so team.member.role_changed sat in the webhook catalog — and was offered as
a Zapier and n8n trigger — while being impossible to fire.
How it fails
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks team-member:update-role.
TEAM_TIER_REQUIREDthe caller's platform tier does not include Teams.
RESOURCE_NOT_FOUNDno such team, or user_id is not a member of it. The owner also returns 404 here, because the owner has no membership row to change.
VALIDATION_FAILEDunknown role code.
How is this guide?
Last updated on