297 Add Access v2 Endpoints

verkadaModule/Public/Access/Add-VerkadaAccessGroup.ps1

@@ -15,7 +15,7 @@ function Add-VerkadaAccessGroup{
 		This will add the access group with the name "NewGroup".  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Add-VerkadaAccessGroup -name 'NewGroup' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Add-VerkadaAccessGroup -name 'NewGroup' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will add the access group with the name "NewGroup".  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Add-VerkadaAccessUserCard.ps1

@@ -16,7 +16,7 @@ function Add-VerkadaAccessUserCard{
 		This will add a badge in the HID format with facility code 111 and card number 55555 to the user specified.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Add-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -type 'HID' -facilityCode 111 -cardNumber 55555 -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Add-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -type 'HID' -facilityCode 111 -cardNumber 55555 -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will add an Access credential in the HID format with facility code 111 and card number 55555 to the user specified.  The token is submitted as a parameter in the call.
 
 		.EXAMPLE

verkadaModule/Public/Access/Add-VerkadaAccessUserLicensePlate.ps1

@@ -16,7 +16,7 @@ function Add-VerkadaAccessUserLicensePlate{
 		This will add the license plate ABC123 to the Access user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 as a credential.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Add-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -name 'Users License Plate' -active $true -x_verkada_token 'a366ef47-2c20-4d35-a90a-10fd2aee113a'
+		Add-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -name 'Users License Plate' -active $true -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will add the license plate ABC123 to the Access user with externalId newUserUPN@contoso.com as a credential and mark it active.  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Add-VerkadaAccessUserMfaCode.ps1

@@ -15,7 +15,7 @@ function Add-VerkadaAccessUserMfaCode{
 		This adds the MFA code 9567 to the Access user's profile with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3. The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Add-VerkadaAccessUserMfaCode -mfaCode '9567' -externalId 'newUserUPN@contoso.com' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Add-VerkadaAccessUserMfaCode -mfaCode '9567' -externalId 'newUserUPN@contoso.com' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This adds the MFA code 9567 to the Access user's profile with externalId newUserUPN@contoso.com. The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Disable-VerkadaAccessUserCard.ps1

@@ -15,7 +15,7 @@ function Disable-VerkadaAccessUserCard{
 		This will deactivate the credential with cardId 10110010000000000000001011 for the Access user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 as a credential.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Disable-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -cardId '10110010000000000000001011' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Disable-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -cardId '10110010000000000000001011' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will deactivate the credential with cardId 10110010000000000000001011 for the Access user with externalId newUserUPN@contoso.com as a credential.  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Disable-VerkadaAccessUserFaceUnlock.ps1

@@ -0,0 +1,107 @@
+function Disable-VerkadaAccessUserFaceUnlock{
+	<#
+		.SYNOPSIS
+		Disabled Face Unlock using https://apidocs.verkada.com/reference/deletefaceunlockdisableexternaluserviewv2 or https://apidocs.verkada.com/reference/deletefaceunlockdisableuserviewv2.
+
+		.DESCRIPTION
+		Disable face unlock for a user. This will delete their face credential and disable the face unlock access method. Any pending mobile enrollment invitations for this user will also be deleted.
+		The reqired token can be directly submitted as a parameter, but is much easier to use Connect-Verkada to cache this information ahead of time and for subsequent commands.
+
+		.LINK
+		https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Disable-VerkadaAccessUserFaceUnlock.md
+
+		.EXAMPLE
+		Disable-VerkadaAccessUserFaceUnlock -externalId 'newUserUPN@contoso.com'
+		This will disable Face Unlock for the user with externalId newUserUPN@contoso.com and will delete the existing face credential..  The token will be populated from the cache created by Connect-Verkada.
+
+		.EXAMPLE
+		Disable-VerkadaAccessUserFaceUnlock -userId '801c9551-b04c-4293-84ad-b0a6aa0588b3' -x_verkada_auth_api 'v2_sd78d9verkada-token'
+		This will disable Face Unlock for the user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 and will delete the existing face credential.  The token is submitted as a parameter in the call.
+	#>
+	[CmdletBinding(PositionalBinding = $true, DefaultParameterSetName = 'user_id')]
+	[Alias("Disable-VrkdaAcUsrFaceUnlk","d-VrkdaAcUsrFaceUnlk")]
+	param (
+		#The UUID of the user
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'user_id')]
+		[ValidateNotNullOrEmpty()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[Alias('user_id')]
+		[String]$userId,
+		#unique identifier managed externally provided by the consumer
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'external_id')]
+		[ValidateNotNullOrEmpty()]
+		[Alias('external_id')]
+		[String]$externalId,
+		#The public API token obatined via the Login endpoint to be used for calls that hit the public API gateway
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[String]$x_verkada_auth_api = $Global:verkadaConnection.x_verkada_auth_api,
+		#The region of the public API to be used
+		[Parameter()]
+		[ValidateSet('api','api.eu','api.au')]
+		[String]$region='api',
+		#Version designation for which version of the function to use
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[ValidateSet('v2')]
+		[string]$version='v2',
+		#Switch to write errors to file
+		[Parameter()]
+		[switch]$errorsToFile
+	)
+
+	begin {
+		#parameter validation
+		if ([string]::IsNullOrEmpty($x_verkada_auth_api)) {throw "x_verkada_auth_api is missing but is required!"}
+		$myErrors = @()
+	} #end begin
+
+	process {
+		switch ($PSCmdlet.ParameterSetName) {
+			'external_id' {
+				$url = "https://$($region).verkada.com/$($version)/access/external_users/$($externalId)/face_unlock"
+				if ([string]::IsNullOrEmpty($externalId)) {throw "externalId is missing but is required!"}
+				$ident = $externalId
+			}
+			'user_id' {
+				$url = "https://$($region).verkada.com/$($version)/access/users/$($userId)/face_unlock"
+				if ([string]::IsNullOrEmpty($userId)) {throw "userId is missing but is required!"}
+				$ident = $userId
+			}
+		}
+		$body_params = @{}
+
+		$query_params = @{}
+
+		try {
+			$response = Invoke-VerkadaRestMethod $url $x_verkada_auth_api $query_params -body_params $body_params -method DELETE
+			"Successfully disabled Face Unlock for $($ident) $($response | ConvertTo-Json -Compress)"
+		}
+		catch [Microsoft.PowerShell.Commands.HttpResponseException] {
+			$err = $_.ErrorDetails | ConvertFrom-Json
+			$errorMes = $_ | Convertto-Json -WarningAction SilentlyContinue
+			$err | Add-Member -NotePropertyName StatusCode -NotePropertyValue (($errorMes | ConvertFrom-Json -Depth 100 -WarningAction SilentlyContinue).Exception.Response.StatusCode) -Force
+			$msg = "$($err.StatusCode) - $($err.message)"
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+		catch [VerkadaRestMethodException] {
+			$msg = $_.ToString()
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+	} #end process
+
+	end {
+		if ($errorsToFile.IsPresent){
+			if (![string]::IsNullOrEmpty($myErrors)){
+				Get-Date | Out-File ./errors.txt -Append
+				$myErrors | Out-File ./errors.txt -Append
+			}
+		}
+	} #end end
+} #end function

verkadaModule/Public/Access/Disable-VerkadaAccessUserLicensePlate.ps1

@@ -15,7 +15,7 @@ function Disable-VerkadaAccessUserLicensePlate{
 		This will deactivate the license plate ABC123 for the Access user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 as a credential.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Disable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Disable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will deactivate the license plate ABC123 for the Access user with externalId newUserUPN@contoso.com as a credential.  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Enable-VerkadaAccessUserCard.ps1

@@ -15,7 +15,7 @@ function Enable-VerkadaAccessUserCard{
 		This will activate the credential with cardId 10110010000000000000001011 for the Access user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 as a credential.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Enable-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -cardId '3f3b3e4d-1a67-4b88-a321-43c5e502991c' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Enable-VerkadaAccessUserCard -externalId 'newUserUPN@contoso.com' -cardId '3f3b3e4d-1a67-4b88-a321-43c5e502991c' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will activate the credential with cardId 10110010000000000000001011 for the Access user with externalId newUserUPN@contoso.com as a credential.  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Enable-VerkadaAccessUserFaceUnlock.ps1

@@ -0,0 +1,166 @@
+function Enable-VerkadaAccessUserFaceUnlock{
+	<#
+		.SYNOPSIS
+		Enables face unlock for an Access user using https://apidocs.verkada.com/reference/postfaceunlockcopyuserphotoexternaluserviewv2, https://apidocs.verkada.com/reference/postfaceunlockuploadphotoexternaluserviewv2, https://apidocs.verkada.com/reference/postfaceunlockcopyuserphotouserviewv2, and https://apidocs.verkada.com/reference/postfaceunlockuploadphotouserviewv2
+
+		.DESCRIPTION
+		Enable face unlock for a user by using their existing profile photo by uploading a new photo. This will create a face credential from the user's profile photo or by providing a photo via uplaod. If the user already has a face credential and overwrite is False, the request will fail. The profile photo must meet quality requirements for face recognition.
+		The reqired token can be directly submitted as a parameter, but is much easier to use Connect-Verkada to cache this information ahead of time and for subsequent commands.
+
+		.LINK
+		https://github.com/bepsoccer/verkadaModule/blob/master/docs/function-documentation/Enable-VerkadaAccessUserFaceUnlock.md
+
+		.EXAMPLE
+		Enable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com'
+		This will enable Face Unlock for the user with externalId newUserUPN@contoso.com using their existing AC profile photo.  The token will be populated from the cache created by Connect-Verkada.
+
+		.EXAMPLE
+		Enable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -imagePath './myPicture.png' -overwrite $true -x_verkada_auth_api 'v2_sd78d9verkada-token'
+		This will enable Face Unlock for the user with externalId newUserUPN@contoso.com using the photo specified in the imagePath, ./myPicture.png, and will overwrite the existing face credential if it exists.  The token is submitted as a parameter in the call.
+
+		.EXAMPLE
+		Enable-VerkadaAccessUserLicensePlate -userId '801c9551-b04c-4293-84ad-b0a6aa0588b3'
+		This will enable Face Unlock for the user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 using their existing AC profile photo.  The token will be populated from the cache created by Connect-Verkada.
+
+		.EXAMPLE
+		Enable-VerkadaAccessUserLicensePlate -userId '801c9551-b04c-4293-84ad-b0a6aa0588b3' -imagePath './801c9551-b04c-4293-84ad-b0a6aa0588b3.png' -overwrite $true -x_verkada_auth_api 'v2_sd78d9verkada-token'
+		This will enable Face Unlock for the user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 using the photo specified in the imagePath, ./801c9551-b04c-4293-84ad-b0a6aa0588b3.png, and will overwrite the existing face credential if it exists.  The token is submitted as a parameter in the call.
+	#>
+	[CmdletBinding(PositionalBinding = $true, DefaultParameterSetName = 'external_profilePhoto')]
+	[Alias("Enable-VrkdaAcUsrFaceUnlk","e-VrkdaAcUsrFaceUnlk")]
+	param (
+		#The UUID of the user
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'user_profilePhoto')]
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'user_upload')]
+		[ValidateNotNullOrEmpty()]
+		[ValidatePattern('^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$')]
+		[Alias('user_id')]
+		[String]$userId,
+		#unique identifier managed externally provided by the consumer
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'external_profilePhoto')]
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'external_upload')]
+		[ValidateNotNullOrEmpty()]
+		[Alias('external_id')]
+		[String]$externalId,
+		#This is the path the image will be uploaded from
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'user_upload')]
+		[Parameter(ValueFromPipelineByPropertyName = $true, Mandatory = $true, ParameterSetName = 'external_upload')]
+		[ValidateNotNullOrEmpty()]
+		[ValidatePattern('^.*\.(jpg|jpeg|png)$')]
+		[string]$imagePath,
+		#The flag that states whether to overwrite the existing profile photo
+		[Parameter(ValueFromPipelineByPropertyName = $true)]
+		[bool]$overwrite=$false,
+		#The public API token obatined via the Login endpoint to be used for calls that hit the public API gateway
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[String]$x_verkada_auth_api = $Global:verkadaConnection.x_verkada_auth_api,
+		#The region of the public API to be used
+		[Parameter()]
+		[ValidateSet('api','api.eu','api.au')]
+		[String]$region='api',
+		#Version designation for which version of the function to use
+		[Parameter()]
+		[ValidateNotNullOrEmpty()]
+		[ValidateSet('v2')]
+		[string]$version='v2',
+		#Switch to write errors to file
+		[Parameter()]
+		[switch]$errorsToFile
+	)
+
+	begin {
+		#parameter validation
+		if ([string]::IsNullOrEmpty($x_verkada_auth_api)) {throw "x_verkada_auth_api is missing but is required!"}
+		$myErrors = @()
+	} #end begin
+
+	process {
+		switch ($PSCmdlet.ParameterSetName) {
+			'external_profilePhoto' {
+				$url = "https://$($region).verkada.com/$($version)/access/external_users/$($externalId)/face_unlock/copy_user_photo"
+				if ([string]::IsNullOrEmpty($externalId)) {throw "externalId is missing but is required!"}
+
+				#check to see if an AC profile photo exists
+				if ((Get-VerkadaAccessUser -externalId $externalId -x_verkada_auth_api $x_verkada_auth_api).has_profile_photo){
+					$upload = $false
+				} else {
+					throw "$($externalId) has no current AC profile photo"
+				}
+			}
+			'external_upload' {
+				$url = "https://$($region).verkada.com/$($version)/access/external_users/$($externalId)/face_unlock/upload_photo"
+				if ([string]::IsNullOrEmpty($externalId)) {throw "externalId is missing but is required!"}
+				if ([string]::IsNullOrEmpty($imagePath)) {throw "imagePath is missing but is required!"}
+				$upload = $true
+
+				$form = @{
+					file				= Get-Item -Path $imagePath
+					'overwrite'	= $overwrite
+				}
+			}
+			'user_profilePhoto' {
+				$url = "https://$($region).verkada.com/$($version)/access/users/$($userId)/face_unlock/copy_user_photo"
+				if ([string]::IsNullOrEmpty($userId)) {throw "userId is missing but is required!"}
+
+				#check to see if an AC profile photo exists
+				if ((Get-VerkadaAccessUser -userId $userId -x_verkada_auth_api $x_verkada_auth_api).has_profile_photo){
+					$upload = $false
+				} else {
+					throw "$($userId) has no current AC profile photo"
+				}
+			}
+			'user_upload' {
+				$url = "https://$($region).verkada.com/$($version)/access/users/$($userId)/face_unlock/upload_photo"
+				if ([string]::IsNullOrEmpty($userId)) {throw "userId is missing but is required!"}
+				if ([string]::IsNullOrEmpty($imagePath)) {throw "imagePath is missing but is required!"}
+				$upload = $true
+
+				$form = @{
+					file				= Get-Item -Path $imagePath
+					'overwrite'	= $overwrite
+				}
+			}
+		}
+
+		$body_params = @{}
+
+		$query_params = @{}
+
+		try {
+			if ($upload) {
+				$response = Invoke-VerkadaFormCall $url $form -query_params $query_params -x_verkada_auth_api $x_verkada_auth_api -method POST
+				return "Successfully uploaded $imagePath to $($response | ConvertTo-Json -Compress)"
+			} else {
+				$response = Invoke-VerkadaRestMethod $url $x_verkada_auth_api $query_params -body_params $body_params -method POST
+				return $response
+			}
+		}
+		catch [Microsoft.PowerShell.Commands.HttpResponseException] {
+			$err = $_.ErrorDetails | ConvertFrom-Json
+			$errorMes = $_ | Convertto-Json -WarningAction SilentlyContinue
+			$err | Add-Member -NotePropertyName StatusCode -NotePropertyValue (($errorMes | ConvertFrom-Json -Depth 100 -WarningAction SilentlyContinue).Exception.Response.StatusCode) -Force
+			$msg = "$($err.StatusCode) - $($err.message)"
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+		catch [VerkadaRestMethodException] {
+			$msg = $_.ToString()
+			$msg += ": $(($query_params + $body_params) | ConvertTo-Json -Compress)"
+			Write-Error $msg
+			$myErrors += $msg
+			$msg = $null
+		}
+	} #end process
+
+	end {
+		if ($errorsToFile.IsPresent){
+			if (![string]::IsNullOrEmpty($myErrors)){
+				Get-Date | Out-File ./errors.txt -Append
+				$myErrors | Out-File ./errors.txt -Append
+			}
+		}
+	} #end end
+} #end function

verkadaModule/Public/Access/Enable-VerkadaAccessUserLicensePlate.ps1

@@ -15,7 +15,7 @@ function Enable-VerkadaAccessUserLicensePlate{
 		This will activate the license plate ABC123 for the Access user with userId 801c9551-b04c-4293-84ad-b0a6aa0588b3 as a credential.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Enable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Enable-VerkadaAccessUserLicensePlate -externalId 'newUserUPN@contoso.com' -licensePlateNumber 'ABC123' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will activate the license plate ABC123 for the Access user with externalId newUserUPN@contoso.com as a credential.  The token is submitted as a parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]

verkadaModule/Public/Access/Get-VerkadaAccessEvents.ps1

@@ -15,7 +15,7 @@ function Get-VerkadaAccessEvents{
 		This will return all the access events from 1 hour in the past until present.  The token will be populated from the cache created by Connect-Verkada.
 
 		.EXAMPLE
-		Get-VerkadaAccessEvents -start_time 'January 1, 2025 9:00:00AM' -end_time 'February 8, 2025 10:30:00PM' -x_verkada_auth_api 'sd78ds-uuid-of-verkada-token'
+		Get-VerkadaAccessEvents -start_time 'January 1, 2025 9:00:00AM' -end_time 'February 8, 2025 10:30:00PM' -x_verkada_auth_api 'v2_sd78d9verkada-token'
 		This will return all the access events from Jan 1 at 9am to Feb 8 at 10:30pm.  The token is submitted as parameter in the call.
 	#>
 	[CmdletBinding(PositionalBinding = $true)]