Add-TeamUser -Role Owner: add an owner (or member) to a Microsoft Team

Add-TeamUser -GroupId ID -User UPN -Role Owner adds a user to a team as an owner. Without -Role, the user is added as a member, the documented default. The reference: "Member or Owner. If Owner is specified then the user is also added as a member to the Team backed by unified group." The cmdlet comes from the MicrosoftTeams module and needs Connect-MicrosoftTeams with a Teams Administrator account, or an account that owns the team.

Connect-MicrosoftTeams
$team = Get-Team -DisplayName "Project Atlas"
Add-TeamUser -GroupId $team.GroupId -User lena@contoso.com -Role Owner
Add-TeamUser -GroupId $team.GroupId -User marco@contoso.com          # member
Get-TeamUser -GroupId $team.GroupId -Role Owner

Allowed values

-Role is validated by PowerShell before anything is sent to Teams, so the allowed values can be checked offline. MicrosoftTeams 8.0.0 in Windows PowerShell 5.1, no connection:

Import-Module MicrosoftTeams
$add = (Get-Command Add-TeamUser).Parameters['Role']
"Add-TeamUser -Role: " + (($add.Attributes | Where-Object { $_ -is [System.Management.Automation.ValidateSetAttribute] }).ValidValues -join ', ')
$get = (Get-Command Get-TeamUser).Parameters['Role']
"Get-TeamUser -Role: " + (($get.Attributes | Where-Object { $_ -is [System.Management.Automation.ValidateSetAttribute] }).ValidValues -join ', ')
try { Add-TeamUser -GroupId 00000000-0000-0000-0000-000000000000 -User x@contoso.com -Role Admin -ErrorAction Stop } catch { $_.Exception.Message }

Add-TeamUser -Role: Owner, Member
Get-TeamUser -Role: Owner, Member, Guest
Cannot validate argument on parameter 'Role'. The argument "Admin" does not belong to the set "Owner,Member" specified by the ValidateSet attribute. Supply an argument that is in the set and then try the command again.

So Get-TeamUser -Role Guest can list guests, but Add-TeamUser cannot add someone "as guest": the value is rejected with the ValidateSet message above.

Pitfalls

• GroupId, not the name. -GroupId takes the team's group ID (a GUID); look it up with Get-Team -DisplayName (Get-Team and New-Team).
• Last owner. The Remove-TeamUser reference notes that the last owner cannot be removed from the team, so add a second owner before removing the first.
• Propagation delay. A new owner can take some time to appear in the Teams client, because membership is synchronized from the Microsoft 365 group.
• Not connected. Without a session the cmdlet fails with the error on You must call Connect-MicrosoftTeams.
• ValidateSet errors elsewhere. Other Teams cmdlets validate their values the same way, for example New-Team -Visibility.

FAQ