Update team member role

Changes a team member's role. Reference the target role by its ID, which you can get from the List roles API.

Authenticate with a global API token (pass team_name to choose the team) or an Uptime API token (already scoped to its team).

Organization-wide roles (admin and billing_admin) apply across every team in the organization, so assigning billing_admin updates the member in all of their teams. See Manage roles for what each role can access.

Assigning a role the member already has is a no-op that still returns 200 with the member, so this endpoint is safe to call repeatedly — for example from an automation that syncs roles on every on-call rotation change.

Changing a role to or from admin is not permitted via the API. Manage admins in Settings → Team members.

POST https://betterstack.com/api/v2/team-members/{id}/change-role/{role_id}

URL parameters

required string

The ID of the team member, as returned by the List or Get team members API. Pending invitations cannot have their role changed this way — cancel and re-invite them instead.

role_id

required string

The ID of the role to assign, as returned by the List roles API. Custom roles are supported. The response returns role as custom for a custom role.

Query parameters

team_name

string

Required if using a global API token to specify the team. Ignored for team-scoped Uptime API tokens.

Headers

Authorization

required string

Bearer $TOKEN

200

The role was changed (or already matched). Returns the updated team member.

Response body

{
  "data": {
    "id": "101",
    "type": "team_member",
    "attributes": {
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Smith",
      "created_at": "2023-10-26T10:00:00.000Z",
      "role": "team_lead",
      "role_id": 103,
      "mobile_app_platforms": []
    }
  }
}

401

Authentication failed due to a missing or invalid token.

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}

403

The API token is read-only.

Response body

{
  "errors": "This API token is read-only and cannot be used for write operations."
}

403

The target role is admin.

Response body

{
  "errors": "Assigning the admin role is not allowed via API."
}

403

The team member currently has the admin role.

Response body

{
  "errors": "Changing an admin's role is not allowed via API."
}

404

No role with the given ID exists in the organization.

Response body

{
  "errors": "Resource type role with id = 999 was not found"
}

404

The team member with the specified ID was not found in the team.

Response body

{
  "errors": "Resource type user with id = 999 was not found"
}

409

Another role change for this user is already in progress.

Response body

{
  "errors": "Another role change for this user is in progress. Please try again."
}

Example cURL

Change role

Copied!

curl --request POST \
  --url "https://betterstack.com/api/v2/team-members/101/change-role/103" \
  --header "Authorization: Bearer $TOKEN"

Invite a team member

Remove a team member from team by ID

Explore documentation

Update team member role

Example cURL

Please accept cookies