From 771ee9225abcba98bebf0be9610f9561a3d73f39 Mon Sep 17 00:00:00 2001
From: radu-cristea-15 <radu.cristea@teamviewer,com>
Date: Fri, 7 Nov 2025 15:27:42 +0100
Subject: [PATCH] Add new cmdlet Get-TeamViewerRoleByUser

---
 Cmdlets/Public/Get-TeamViewerRoleByUser.ps1   | 40 +++++++++
 Docs/Help/Get-TeamViewerRoleByUser.md         | 84 +++++++++++++++++++
 Docs/TeamViewerPS.md                          |  2 +
 .../Public/Get-TeamViewerRoleByUser.Tests.ps1 | 57 +++++++++++++
 4 files changed, 183 insertions(+)
 create mode 100644 Cmdlets/Public/Get-TeamViewerRoleByUser.ps1
 create mode 100644 Docs/Help/Get-TeamViewerRoleByUser.md
 create mode 100644 Tests/Public/Get-TeamViewerRoleByUser.Tests.ps1

diff --git a/Cmdlets/Public/Get-TeamViewerRoleByUser.ps1 b/Cmdlets/Public/Get-TeamViewerRoleByUser.ps1
new file mode 100644
index 0000000..da9145a
--- /dev/null
+++ b/Cmdlets/Public/Get-TeamViewerRoleByUser.ps1
@@ -0,0 +1,40 @@
+function Get-TeamViewerRoleByUser {
+    param(
+        [Parameter(Mandatory = $true)]
+        [securestring]
+        $ApiToken,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateScript({ $_ | Resolve-TeamViewerUserId })]
+        [Alias('UsersId')]
+        [Alias('Id')]
+        [string]
+        $UserId
+    )
+
+    begin {
+        $copyUri = "$(Get-TeamViewerApiUri)/users/$userId/userroles"
+        $parameters = $null
+        $list = @()
+    }
+    process {
+        $resourceUri = $copyUri
+        do {
+            $response = Invoke-TeamViewerRestMethod `
+                -ApiToken $ApiToken `
+                -Uri $resourceUri `
+                -Method Get `
+                -Body $parameters `
+                -WriteErrorTo $PSCmdlet `
+                -ErrorAction Stop
+
+            if ($response.assignedRoleIds -and $response.assignedRoleIds.Count -gt 0) {
+                $list += $response.assignedRoleIds
+            }
+            if ($response.nextPaginationToken) {
+                $resourceUri = $copyUri + '?paginationToken=' + $response.nextPaginationToken
+            }
+        } while ($response.nextPaginationToken)
+        return $list
+    }
+}
diff --git a/Docs/Help/Get-TeamViewerRoleByUser.md b/Docs/Help/Get-TeamViewerRoleByUser.md
new file mode 100644
index 0000000..c372639
--- /dev/null
+++ b/Docs/Help/Get-TeamViewerRoleByUser.md
@@ -0,0 +1,84 @@
+---
+external help file: TeamViewerPS-help.xml
+Module Name: TeamViewerPS
+online version: https://github.com/teamviewer/TeamViewerPS/blob/main/Docs/Help/Get-TeamViewerUserByRole.md
+schema: 2.0.0
+---
+
+# Get-TeamViewerRoleByUser
+
+## SYNOPSIS
+
+Returns the assigned role ids of the user or null.
+
+## SYNTAX
+
+```powershell
+Get-TeamViewerRoleByUser [-ApiToken] <SecureString> [-UserId] <Object> [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Lists the assigned roles of a user in the TeamViewer company associated with the API access token. If no role is assigned or user id is unknown, null is returned.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS /> Get-TeamViewerRoleByUser -UserId "u123456777"
+```
+
+Lists the assigned roles of the user with the ID u123456777.
+
+## PARAMETERS
+
+### -ApiToken
+
+The TeamViewer API access token.
+
+```yaml
+Type: SecureString
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -UserId
+
+User to list its assigned roles.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases: UsersId
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+### UUID[]
+
+An array of `UUID` objects.
+
+## NOTES
+
+## RELATED LINKS
diff --git a/Docs/TeamViewerPS.md b/Docs/TeamViewerPS.md
index e077a17..b8581d3 100644
--- a/Docs/TeamViewerPS.md
+++ b/Docs/TeamViewerPS.md
@@ -77,6 +77,8 @@ The following functions are available in this category:
 
 [`Remove-TeamViewerUserTFA`](Help/Remove-TeamViewerUserTFA.md)
 
+['Get-TeamViewerRoleByUser'](Help/Get-TeamViewerRoleByUser.md)
+
 ['Get-TeamViewerEffectivePermission'](Help/Get-TeamViewerEffectivePermission.md)
 
 ## User Groups
diff --git a/Tests/Public/Get-TeamViewerRoleByUser.Tests.ps1 b/Tests/Public/Get-TeamViewerRoleByUser.Tests.ps1
new file mode 100644
index 0000000..4452d1e
--- /dev/null
+++ b/Tests/Public/Get-TeamViewerRoleByUser.Tests.ps1
@@ -0,0 +1,57 @@
+
+Describe 'Get-TeamViewerUserByRole' {
+    Context 'When retrieving role assignments' {
+        BeforeEach {
+            . "$PSScriptRoot\..\..\Cmdlets\Public\Get-TeamViewerRoleByUser.ps1"
+
+            @(Get-ChildItem -Path "$PSScriptRoot\..\..\Cmdlets\Private\*.ps1") | `
+                ForEach-Object { . $_.FullName }
+
+            Mock Get-TeamViewerApiUri { '//unit.test' }
+            $responses = [System.Collections.Queue]::new()
+            $responses.Enqueue([PSCustomObject]@{
+                    currentPaginationToken = $null
+                    nextPaginationToken    = 'Test1'
+                    assignedRoleIds        = @('f37001f9-bc3e-452e-9533-d81b0916be09')
+                })
+            $responses.Enqueue([PSCustomObject]@{
+                    currentPaginationToken = $null
+                    nextPaginationToken    = $null
+                    assignedRoleIds        = @('f47001f9-bc3e-452e-9533-d81b0916be09')
+                })
+            Mock Invoke-TeamViewerRestMethod -MockWith {
+                if ($responses.Count -gt 0) {
+                    return $responses.Dequeue()
+                }
+            }
+            $testApiToken = [securestring]@{}
+            $null = $testApiToken
+            $testUserId = 'u123456777'
+            $null = $testUserId
+        }
+        It 'Should call the correct API endpoint' {
+            Get-TeamViewerRoleByUser -ApiToken $testApiToken -UserId $testUserId
+
+            Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+                $ApiToken -eq $testApiToken -And `
+                    $Uri -eq "//unit.test/users/$testUserId/userroles?paginationToken=Test1" -And `
+                    $Method -eq 'Get' 
+            }
+        }
+        It 'Should return assigned users' {
+            $result = Get-TeamViewerRoleByUser -ApiToken $testApiToken -UserId $testUserId
+            $result | Should -HaveCount 2
+        }
+        It 'Should return an empty list if no roles are assigned' {
+            Mock Invoke-TeamViewerRestMethod -MockWith {
+                [PSCustomObject]@{
+                    currentPaginationToken = $null
+                    nextPaginationToken    = $null
+                    assignedRoleIds        = @()
+                }
+            }
+            $result = Get-TeamViewerRoleByUser -ApiToken $testApiToken -UserId $testUserId
+            $result | Should -HaveCount 0
+        }
+    }
+}