Personal Access Tokens

Personal access tokens (PAT) are used for unattented authentication to the Update Service web API.

Creating new access tokens

  1. To create a new access token, you can access the Personal Tokens menu by clicking on the user profile. Step1

  2. Once you are in the Personal Tokens menu, you can check the status of your currently created tokens (Active, Revoked, or Expired), edit their information, and create new tokens. Step2

  3. Simply fill out the fields in the creation modal, and click submit. Fields such as name and description are purely informative to help users identify created tokens. Step3

  4. After creating the token, a token hash will be provided to you as the authentication key for this user. Step4

    Note

    It is important to note that the token security code is presented only at token creation time and is not saved in the database. You can use the copy button as a convenient way to copy token code to the clipboard.

Using access tokens in Update Service

To use access tokens in Update Service with REST API calls, simply add the code generated on the HTTP Authorization header as follows:

Authorization: Bearer {token}

How to authenticate the cmdlets in a PowerShell session

You can authenticate your Powershell session with specific cmdlets when you're using cmdlets and authentication. In the UpdateServiceServer module, use the Connect-UssServer cmdlet. In the UpdateService module, use the Connect-UscServer cmdlet. These cmdlets take a server URL and a PSCredential object for authentication. Here's how you can create a PSCredential object:

$UserName = "your-user-name@here.com"
$SecurePat = "Generated PAT" | ConvertTo-SecureString -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential -ArgumentList ($UserName, $SecurePat)
Connect-UssServer -Credential $Credential -Server "SERVER URL"

How to authenticate individual server cmdlets

You can also authenticate individual server cmdlets (UpdateServiceServer), that require authentication with the -Credential parameter. For instance Get-UssPackageVersion requires authentication to access the server:

$UserName = "your-user-name@here.com"
$SecurePat = "Generated PAT" | ConvertTo-SecureString -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential -ArgumentList ($UserName, $SecurePat)
Get-UssPackageVersion -PackageId 'ls-central-app' -VersionQuery '' -Credential $Credential -Server "SERVER URL"

Take special note of the cmdlets, Copy-UssPackageFromServer and Copy-UssInstallerFromServer which communicate with two servers. These cmdlets require two sets of credentials, one for the source server and one for the destination server. Here's an example of how to use these cmdlets:

$SourceServer = 'https://updateservice.lsretail.com'
$Server = 'http://localhost:8060'
$UserName = "your-user-name@here.com"
$SecurePat = "password" | ConvertTo-SecureString -AsPlainText -Force
$Credential = New-Object System.Management.Automation.PSCredential -ArgumentList ($UserName, $SecurePat)
Copy-UssPackageFromServer -PackageId 'example-package' -SourceServer $SourceServer -SourceCredential $Credential -Server $Server

How to authenticate client service

See here for further information on how to authenticate the client service.

Revoking Access Tokens

If you wish to cancel an issued token, simply access it by clicking on the token list and clicking revoke on the following popup.

Revoke