Introduction
This guide describes how to programmatically rotate a Teramind user password using the REST API. It is intended for Privileged Access Management (PAM) integrations and other automated credential rotation workflows.
Overview
Password rotation uses the existing Teramind agent API:
Look up the user by email address and obtain their
agent_id.Update the user's password via
PATCH /agent/{id}.
The caller must authenticate with an Access Token created by a Teramind Administrator. When using x-access-token, no additional confirmation token or administrator password is required - the Access Token itself serves as authorization for sensitive changes.
Important: When an administrator changes another user's password, the target user will be required to change their password on their next login.
Prerequisites
Teramind instance URL (for example,
https://<your-instance-host)>An administrator account with permission to configure agent passwords
A Teramind Access Token created by that administrator
PowerShell 5.1 or later (for the sample script below)
The new password must comply with your instance password policy
API Base URL
All requests are sent to:
https://<your-instance-host>/tm-api
Replace <your-instance-host> with your Teramind server hostname. For example: https://acme.com/tm-api. If you don't have a hostname set, use the IP address. For example: https://10.52.51.122/tm-api.
Authentication: Access Token (System-to-System)
API requests must be authenticated with a Teramind Access Token. This is the supported approach for system-to-system integrations such as PAM: your external system presents the token on each call without logging in through the web UI.
Create the token once in the Teramind UI, store it in your PAM vault or secrets manager, and send it on every request in the x-access-token header.
Create an Access Token in the UI
Step-by-step
Log in to Teramind as an Administrator.
Open the user menu in the top-right corner of the page (your profile icon / name).
Click Access Tokens.
On the My Tokens tab, click Add Access Token.
Enter a descriptive name for the token (for example,
PAM Password Rotation).Click Create.
A confirmation dialog displays the generated token value. Copy the token immediately - it is shown only once and cannot be retrieved later.
Click Done to close the dialog.
The new token appears in the list by name. Only the name is shown afterwards; the secret value is not stored in the UI.
For more information about how to create an access token, check out the Access Token section in the User Guide.
Using the token in API requests
Pass the copied value on every API call using the x-access-token request header:
x-access-token: <your-access-token>
Store the token in your PAM vault or secrets manager. If it is lost or compromised, delete it from the Access Tokens page and create a new one.
Note: Administrators can also view tokens created by other users on the All Tokens tab. The Access Token inherits the permissions of the administrator who created it.
Step 1 — Find User by Email
Look up the target user and read their agent_id.
Request
GET /tm-api/agent/{email} x-access-token: <your-access-token>URL-encode the email address. For example, [email protected] becomes admin%40example.com.
Example
GET /tm-api/agent/admin%40example.com
Response
{
"agent_id": 42,
"email_address": "[email protected]",
"first_name": "Admin",
"last_name": "User",
"role": 1
}
Save the agent_id value for Step 2.
Step 2 — Update the Password
Set a new password for the user identified in Step 1.
Note: Interactive UI sessions require a separate confirmation step (administrator password prompt) before sensitive changes. This does not apply to API calls authenticated with x-access-token.
Request
PATCH /tm-api/agent/{agent_id}
x-access-token: <your-access-token>
Content-Type: application/json
{
"newPassword": "NewSecureP@ssw0rd!",
"passwordConfirm": "NewSecureP@ssw0rd!"
}passwordConfirmation is accepted as an alias for passwordConfirm.
Response
A successful update returns the updated agent object:
{
"agent_id": 42,
"email_address": "[email protected]",
"first_name": "Admin",
"last_name": "User",
"role": 1
}
Errors
HTTP Status | Meaning |
400 | Password does not meet policy, or |
401 | Invalid or missing Access Token |
403 | Insufficient permissions ( |
404 | User not found |
PowerShell Example Script
Save the following script as Rotate-TeramindPassword.ps1 and update the configuration variables at the top.
#Requires -Version 5.1
<#
.SYNOPSIS
Rotates a Teramind user password via the REST API.
.NOTES
- Create an Access Token in the Teramind UI: user menu → Access Tokens → Add Access Token.
- The Access Token must belong to a Teramind Administrator.
- The target user will be required to change their password on next login.
#>
# --- Configuration ---
$BaseUrl = "https://<your-instance-host>/tm-api"
$AccessToken = "paste-your-access-token-here"
$TargetUserEmail = "[email protected]"
$NewPassword = "NewSecureP@ssw0rd!"
$SkipCertificateCheck = $false # set $true for self-signed / on-prem certs (testing only)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$headers = @{
"x-access-token" = $AccessToken
"Content-Type" = "application/json"
}
# --- Step 1: Find user by email ---
Write-Host "Looking up user: $TargetUserEmail"
$encodedEmail = [uri]::EscapeDataString($TargetUserEmail)
$agent = Invoke-RestMethod `
-Method Get `
-Uri "$BaseUrl/agent/$encodedEmail" `
-Headers $headers
$agentId = $agent.agent_id
if (-not $agentId) {
throw "User not found or agent_id missing in response."
}
Write-Host "Found user with agent_id: $agentId"
# --- Step 2: Update password ---
Write-Host "Updating password for agent_id: $agentId"
$updateBody = @{
newPassword = $NewPassword
passwordConfirm = $NewPassword
} | ConvertTo-Json
Invoke-RestMethod `
-Method Patch `
-Uri "$BaseUrl/agent/$agentId" `
-Headers $headers `
-Body $updateBody
Write-Host "Password updated successfully."
Write-Host "Note: The user will be required to change their password on next login."
Running the Script
PowerShell -ExecutionPolicy Bypass -File ".\Rotate-TeramindPassword.ps1"
For production PAM integrations, store the Access Token in your PAM vault and invoke the script (or equivalent HTTP calls) on your rotation schedule.
Troubleshooting
SSL certificate error (Could not establish trust relationship for the SSL/TLS secure channel)
This usually means the Teramind server uses a self-signed or internal CA certificate that Windows does not trust. The API call fails before any user lookup happens.
Recommended (production): Install the server's CA certificate into Windows → Trusted Root Certification Authorities, then run the script again.
Workaround (testing / on-prem): Set $SkipCertificateCheck = $true at the top of the script. Only use this on trusted internal networks.
Security Notes
Use HTTPS only. Never send credentials over unencrypted connections.
Store the Access Token securely; do not hard-code it in scripts committed to source control.
Password changes are recorded in the Teramind audit log.
Active sessions for the target user are invalidated when the password is changed.
Related Endpoints
Method | Endpoint | Description |
— | Teramind UI → user menu → Access Tokens | Create Access Token for system-to-system auth |
|
| Look up user by email or agent ID |
|
| Update agent properties, including password |
Full API documentation is available at https://apidoc.dev.teramind.co/