Personal Access Tokens (PAT)

Use personal access tokens (PATs) to securely automate authentication with the Update Service web API and PowerShell cmdlets. This guide walks you through creating, using, and revoking PATs.

Create a Personal Access Token

  1. Open the Personal Tokens menu:
    • Click your user profile and select Personal Tokens.
    • Step1
  2. View and manage tokens:
    • See your tokens’ status (Active, Revoked, Expired), edit, or create new tokens.
    • Step2
  3. Create a new token:
    • Fill in the name and description (for your reference), then submit.
    • Step3
  4. Copy your token value:
    • After creation, you’ll see the token value (token hash). Copy and store it securely—you won’t be able to see it again.
    • Step4
Note

The token value is shown only once. Use the copy button for convenience. If you lose it, you’ll need to create a new token.

Authenticate with Your PAT

To access the Update Service API, you must exchange your PAT for a bearer token. The bearer token is required for all API requests.

1. Exchange your PAT for a bearer token

Send a POST request to the authentication endpoint with your login username and PAT value as query parameters.

POST https://your-server.com/api/v1/PersonalTokens/authenticate?username=your_username&personalToken=token_hash

PowerShell example

$username = "your_username@example.com"
$token = "token_hash" 
# URL encode the parameters to handle special characters
$encodedUsername = [System.Web.HttpUtility]::UrlEncode($username)
$encodedToken = [System.Web.HttpUtility]::UrlEncode($token)
$url = "https://your-server.com/api/v1/PersonalTokens/authenticate?username=$encodedUsername&personalToken=$encodedToken"

$response = Invoke-RestMethod -Uri $url -Method Post
Write-Output $response
Note

URL encoding is essential because PAT values contain special characters like /, +, and = that must be properly encoded in URLs.

Example successful response

{
  "token": "eyJhbGci...", //Bearer token
  "user": {
    "userId": "xxx",
    "email": "user@domain.com",
    "firstName": "xx",
    "lastName": "xxx",
    "fullName": "Jxx",
    "enabled": true
  },
  "tokenExpires": "2023-12-01T08:44:50.0452465+00:00"
}

2. Use the bearer token for API requests

Add the bearer token to the Authorization header for all API calls:

Authorization: Bearer {token}

PowerShell example

# Step 1: Authenticate and get bearer token
$username = "your_username@example.com"
$token = "token_hash"  # Example: "zBI2NWnAy9EWhXfrqZTgmyV662yLXYcY1Hjoq+8X1xkurgYKM2RtogIh0jqdm8DWZuVtdC/pRQo2X0C02ZRyjw=="

# URL encode the parameters to handle special characters
$encodedUsername = [System.Web.HttpUtility]::UrlEncode($username)
$encodedToken = [System.Web.HttpUtility]::UrlEncode($token)
$url = "https://your-server.com/api/v1/PersonalTokens/authenticate?username=$encodedUsername&personalToken=$encodedToken"

$response = Invoke-RestMethod -Uri $url -Method Post
$bearerToken = $response.token

# Step 2: Use the bearer token for API requests
$headers = @{ "Authorization" = "Bearer $bearerToken" }
$apiUrl = "https://your-server.com/api/v1/Packages"
$result = Invoke-RestMethod -Uri $apiUrl -Headers $headers
Write-Output $result
Important

Treat your PAT and bearer token like passwords. Never share them. If you think your token is compromised, revoke it immediately.

Authenticate PowerShell Cmdlets

You can use your PAT to authenticate PowerShell cmdlets for both server and client modules.

Authenticate a session

Use a PSCredential object with your username and PAT value:

$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"

Authenticate individual server cmdlets

Pass the PSCredential object to cmdlets that require authentication:

$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"

Some cmdlets, like Copy-UssPackageFromServer and Copy-UssInstallerFromServer, require credentials for both source and destination servers:

$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

Authenticate the Client Service

See Client Service Authentication for details on authenticating the client service.

Revoke a Personal Access Token

If you need to cancel a token, open the token list, select the token, and click Revoke.

Revoke